[Server][DynamicAdmission] Add atomic runtime enable/disable control

doc/admission-control.md

@@ -46,6 +46,36 @@ serverBuilder.UseAdmissionControl(options =>
 });
 ```
 
+## 运行时启用和停用
+
+Server 包提供运行时控制入口，可在最初未启用接入控制的服务上原子启用，也可停用当前策略并在之后重新启用：
+
+```csharp
+ISharpLinkServer server = serverBuilder.Build();
+
+server.EnableAdmissionControl(options =>
+{
+    options.Global.UseConcurrency(256);
+});
+
+server.DisableAdmissionControl();
+
+server.EnableAdmissionControl(options =>
+{
+    options.Global.UseConcurrency(256);
+});
+```
+
+`EnableAdmissionControl` 会先在发布锁之外构造、校验并解析完整候选策略；只有候选完全可用后才原子发布。回调失败、配置校验失败、生成清单解析失败或并发启用失败都不会改变当前发布状态。回调只用于构造候选配置；方法返回后继续修改调用方保留的 options 对象不会改变已发布策略。
+
+支持的状态转换只有 Disabled → Enabled、Enabled → Disabled 和停用后的再次 Disabled → Enabled。已启用时再次调用 `EnableAdmissionControl` 不表示在线修改策略，而会抛出 `InvalidOperationException`；如需切换策略，先显式停用，再重新启用。对已停用状态重复调用 `DisableAdmissionControl` 是幂等操作。不支持这些运行时入口的自定义 `ISharpLinkServer` 实现会抛出 `NotSupportedException`。
+
+停用只影响之后捕获接入状态的请求，不会取消已经捕获旧 generation 的活动或排队请求，也不会等待这些请求结束。旧 generation 会按正常 retire/reclaim 生命周期完成；在旧 generation 尚未回收时以兼容配置重新启用，会复用稳定 kernel 中兼容的并发、速率、队列和 partition 状态，因此不会重置已消费配额或复制全局记账。
+
+普通的 `DisableAdmissionControl` 不是 Server Stop：它只切换 Admission publication，不触发 `StopAccepting`，也不取消或等待旧 generation。反过来，一旦 Server 已进入 Draining、Stopped 或 Faulted，Admission control plane 就已封口；之后的 `EnableAdmissionControl` 或 `DisableAdmissionControl` 都会抛出 `InvalidOperationException`，且不会再发布任何 program。与 Stop 并发时，结果按同一生命周期 writer lock 的线性化顺序决定。
+
+运行时停用 Admission 不会停用 `ServerResourceGovernor`。调用容量、解码/预接入预算、保留字节和流式字节等服务器资源限制始终独立生效。
+
 ## 排队
 
 只有 `MaxQueuedCalls`、`MaxQueuedBytes` 和 `MaxQueueDelay` 都允许时才等待；任何一个边界耗尽都会立即拒绝。排队仍受调用 deadline 和取消 token 约束。队列保留已解码请求字节，因此 count 与 byte 两个边界都必须配置。
@@ -60,4 +90,4 @@ Partition selector 必须同步、快速、低基数，返回稳定字符串或
 
 permit 覆盖实际服务执行、异步 continuation 和 terminal cleanup。同步抛错、取消、响应队列失败或 Server Stop 都必须释放 permit。相关指标：active permits、queued calls、rejected calls、queue duration、active partitions。
 
-`demo/AdmissionControl` 使用全局并发 1，证明一个调用执行时三个并发请求都收到 `ResourceExhausted`，随后已接入调用正常完成。
+`demo/AdmissionControl` 使用全局并发 1，证明一个调用执行时三个并发请求都收到 `ResourceExhausted`，随后已接入调用正常完成。

src/SharpLink.Server/Admission/AdmissionProgram.cs

@@ -10,6 +10,7 @@ internal sealed class AdmissionProgram
     private const int RetiredMask = int.MinValue;
     private const int UseCountMask = int.MaxValue;
     private static long s_nextGenerationId;
+    private static Action? s_beforeProgramAttachForTests;
 
     private readonly SharpLinkAdmissionController? _controller;
     private readonly AdmissionStateKernel? _kernel;
@@ -28,6 +29,7 @@ internal AdmissionProgram(SharpLinkAdmissionController controller)
             throw new InvalidOperationException("Disabled admission does not create a program generation.");
         _kernel = controller.Kernel;
         GenerationId = Interlocked.Increment(ref s_nextGenerationId);
+        Volatile.Read(ref s_beforeProgramAttachForTests)?.Invoke();
         controller.AttachProgram(this);
         _kernel.RegisterProgram(this);
 
@@ -42,6 +44,16 @@ internal AdmissionProgram(SharpLinkAdmissionController controller)
 
     internal static AdmissionProgram Disabled { get; } = new(0);
 
+    /// <summary>
+    /// Deterministic candidate-construction fault seam after state bindings are acquired but before
+    /// the candidate attaches/registers. The kernel must release those unpublished bindings.
+    /// </summary>
+    internal static Action? BeforeProgramAttachForTests
+    {
+        get => Volatile.Read(ref s_beforeProgramAttachForTests);
+        set => Volatile.Write(ref s_beforeProgramAttachForTests, value);
+    }
+
     internal long GenerationId { get; }
 
     internal bool IsEnabled => _controller is not null;

src/SharpLink.Server/SharpLinkServer.AdmissionProgram.cs

@@ -1,9 +1,11 @@
 namespace SharpLink.Server;
 
-internal sealed partial class SharpLinkServer
+internal sealed partial class SharpLinkServer : ISharpLinkAdmissionRuntimeControl
 {
     private static Action<SharpLinkServer, long, AdmissionProgram>? s_afterAdmissionPublicationReadForTests;
     private static Action<SharpLinkServer, long, AdmissionProgram?>? s_afterAdmissionCaptureForTests;
+    private static Action<SharpLinkServer, AdmissionProgram>? s_afterAdmissionCandidateBuiltForTests;
+    private static Action<SharpLinkServer, AdmissionProgram?>? s_beforeAdmissionPublicationLockForTests;
 
     private AdmissionProgram _admissionProgram = AdmissionProgram.Uninitialized;
 
@@ -23,6 +25,25 @@ internal static Action<SharpLinkServer, long, AdmissionProgram>? AfterAdmissionP
         set => Volatile.Write(ref s_afterAdmissionCaptureForTests, value);
     }
 
+    /// <summary>
+    /// Deterministic control-plane probe. It runs after a public enable candidate is fully built and
+    /// before the lifecycle writer lock is entered.
+    /// </summary>
+    internal static Action<SharpLinkServer, AdmissionProgram>? AfterAdmissionCandidateBuiltForTests
+    {
+        get => Volatile.Read(ref s_afterAdmissionCandidateBuiltForTests);
+        set => Volatile.Write(ref s_afterAdmissionCandidateBuiltForTests, value);
+    }
+
+    /// <summary>
+    /// Deterministic writer probe. A null program represents disable publication.
+    /// </summary>
+    internal static Action<SharpLinkServer, AdmissionProgram?>? BeforeAdmissionPublicationLockForTests
+    {
+        get => Volatile.Read(ref s_beforeAdmissionPublicationLockForTests);
+        set => Volatile.Write(ref s_beforeAdmissionPublicationLockForTests, value);
+    }
+
     internal AdmissionProgram? CurrentAdmissionProgramForTests
     {
         get
@@ -43,6 +64,35 @@ internal AdmissionProgram CreateAdmissionProgramForTests(
         Action<SharpLinkAdmissionControlOptions> configure)
     {
         ArgumentNullException.ThrowIfNull(configure);
+        return CreateAdmissionProgram(configure);
+    }
+
+    internal AdmissionProgram? PublishAdmissionProgramForTests(AdmissionProgram? program)
+        => PublishAdmissionProgram(program, AdmissionPublicationIntent.TestReplacement);
+
+    void ISharpLinkAdmissionRuntimeControl.EnableAdmissionControl(
+        Action<SharpLinkAdmissionControlOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(configure);
+        var candidate = CreateAdmissionProgram(configure);
+        try
+        {
+            Volatile.Read(ref s_afterAdmissionCandidateBuiltForTests)?.Invoke(this, candidate);
+            PublishAdmissionProgram(candidate, AdmissionPublicationIntent.Enable);
+        }
+        catch
+        {
+            candidate.Retire();
+            throw;
+        }
+    }
+
+    void ISharpLinkAdmissionRuntimeControl.DisableAdmissionControl()
+        => PublishAdmissionProgram(null, AdmissionPublicationIntent.Disable);
+
+    private AdmissionProgram CreateAdmissionProgram(
+        Action<SharpLinkAdmissionControlOptions> configure)
+    {
         var controller = _admissionController ??
             throw new InvalidOperationException("Server admission lifecycle owner is unavailable.");
         var options = new SharpLinkAdmissionControlOptions();
@@ -51,14 +101,16 @@ internal AdmissionProgram CreateAdmissionProgramForTests(
         return controller.Kernel.CreateProgram(options, _staticManifests);
     }
 
-    internal AdmissionProgram? PublishAdmissionProgramForTests(AdmissionProgram? program)
+    private AdmissionProgram? PublishAdmissionProgram(
+        AdmissionProgram? program,
+        AdmissionPublicationIntent intent)
     {
         var lifecycle = _admissionController ??
             throw new InvalidOperationException("Server admission lifecycle owner is unavailable.");
         if (program is not null && !ReferenceEquals(program.Kernel, lifecycle.Kernel))
             throw new InvalidOperationException("Admission program belongs to a different server state kernel.");
-        if (program is { IsRetired: true })
-            throw new InvalidOperationException("A retired admission program cannot be published again.");
+
+        Volatile.Read(ref s_beforeAdmissionPublicationLockForTests)?.Invoke(this, program);
 
         AdmissionProgram previous;
         lock (_registryGate)
@@ -68,11 +120,23 @@ internal AdmissionProgram CreateAdmissionProgramForTests(
                 program?.Retire();
                 throw new InvalidOperationException("Admission publication is sealed because the server is stopping.");
             }
+            if (program is { IsRetired: true })
+            {
+                throw new InvalidOperationException("A retired admission program cannot be published again.");
+            }
 
             var replacement = program ?? AdmissionProgram.Disabled;
             previous = ReadAdmissionPublication();
+            if (intent == AdmissionPublicationIntent.Enable && previous.IsEnabled)
+            {
+                program!.Retire();
+                throw new InvalidOperationException("Admission control is already enabled.");
+            }
+            if (intent == AdmissionPublicationIntent.Disable && !previous.IsEnabled)
+                return null;
             if (ReferenceEquals(previous, replacement))
                 return previous.IsEnabled ? previous : null;
+
             Volatile.Write(ref _admissionProgram, replacement);
             if (previous.IsEnabled)
                 previous.Retire();
@@ -130,4 +194,11 @@ private AdmissionProgram ReadAdmissionPublication()
             ? initial
             : observed;
     }
+
+    private enum AdmissionPublicationIntent
+    {
+        Enable,
+        Disable,
+        TestReplacement
+    }
 }

src/SharpLink.Server/SharpLinkServerAdmissionControlExtensions.cs

@@ -0,0 +1,55 @@
+namespace SharpLink.Server;
+
+/// <summary>Runtime admission-control operations for SharpLink servers.</summary>
+public static class SharpLinkServerAdmissionControlExtensions
+{
+    /// <summary>
+    /// Atomically enables admission control for requests that capture admission after this call returns.
+    /// </summary>
+    /// <param name="server">The server whose admission policy is enabled.</param>
+    /// <param name="configure">Builds the complete admission policy before publication.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="server"/> or <paramref name="configure"/> is null.</exception>
+    /// <exception cref="InvalidOperationException">Admission is already enabled, or the server is stopping.</exception>
+    /// <exception cref="NotSupportedException">The server implementation does not support runtime admission control.</exception>
+    public static void EnableAdmissionControl(
+        this ISharpLinkServer server,
+        Action<SharpLinkAdmissionControlOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(server);
+        ArgumentNullException.ThrowIfNull(configure);
+        if (server is not ISharpLinkAdmissionRuntimeControl runtimeControl)
+        {
+            throw new NotSupportedException(
+                "This ISharpLinkServer implementation does not support runtime admission control.");
+        }
+
+        runtimeControl.EnableAdmissionControl(configure);
+    }
+
+    /// <summary>
+    /// Atomically disables admission control for requests that capture admission after this call returns.
+    /// Requests that already captured an enabled generation retain it until terminal completion.
+    /// </summary>
+    /// <param name="server">The server whose admission policy is disabled.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="server"/> is null.</exception>
+    /// <exception cref="InvalidOperationException">The server is stopping.</exception>
+    /// <exception cref="NotSupportedException">The server implementation does not support runtime admission control.</exception>
+    public static void DisableAdmissionControl(this ISharpLinkServer server)
+    {
+        ArgumentNullException.ThrowIfNull(server);
+        if (server is not ISharpLinkAdmissionRuntimeControl runtimeControl)
+        {
+            throw new NotSupportedException(
+                "This ISharpLinkServer implementation does not support runtime admission control.");
+        }
+
+        runtimeControl.DisableAdmissionControl();
+    }
+}
+
+internal interface ISharpLinkAdmissionRuntimeControl
+{
+    void EnableAdmissionControl(Action<SharpLinkAdmissionControlOptions> configure);
+
+    void DisableAdmissionControl();
+}