docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)
Comment/XML-doc changes only: - add summaries to ~10k test methods, fixtures, fakes and helpers (+ <param> on theories, <returns> on async Task methods, <inheritdoc/> on interface implementations the checker can resolve) - strip ~2.6k project-tracking references (WP*, P*-*, row-NN, Task N, #NN, Component-0NN) from comments, keeping the explanatory text; reword false positives in comments only - real docs on fakes implementing BCL/library interfaces (IDisposable, ILogger, IOptionsMonitor, IAsyncLifetime) - reword the last 5 src/ false positives (CWE-1236, failures-1, year-0001, M365) Only non-comment edits: four one-line nested classes split across lines so members can carry docs. Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
@@ -23,6 +23,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
private readonly ISiteStreamSubscriber _subscriber;
|
||||
private readonly ILogger<SiteStreamGrpcServer> _logger;
|
||||
|
||||
/// <summary>Initializes a new instance of the <c>SiteStreamGrpcServerTests</c> class.</summary>
|
||||
public SiteStreamGrpcServerTests()
|
||||
{
|
||||
_subscriber = Substitute.For<ISiteStreamSubscriber>();
|
||||
@@ -47,6 +48,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a stream request is rejected while the server is not ready.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RejectsWhenNotReady()
|
||||
{
|
||||
@@ -62,6 +65,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(StatusCode.Unavailable, ex.StatusCode);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a stream request is rejected once the maximum number of streams is reached.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RejectsWhenMaxStreamsReached()
|
||||
{
|
||||
@@ -93,6 +98,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await stream1Task;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a second stream with the same correlation id cancels the first.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CancelsDuplicateCorrelationId()
|
||||
{
|
||||
@@ -128,6 +135,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await stream2Task;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that cancelling a stream cleans up its server-side state.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CleansUpOnCancellation()
|
||||
{
|
||||
@@ -149,12 +158,14 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.ActiveStreamCount);
|
||||
}
|
||||
|
||||
// --- Host-017 / REQ-HOST-7: site-shutdown ordering ---
|
||||
// --- Site-shutdown ordering ---
|
||||
|
||||
/// <summary>Verifies that cancelling all streams cancels the active streams and refuses new ones.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Host017_CancelAllStreams_CancelsActiveStreamsAndRefusesNewOnes()
|
||||
{
|
||||
// REQ-HOST-7 step (1)+(2): on CoordinatedShutdown the gRPC server must
|
||||
// Shutdown steps (1)+(2): on CoordinatedShutdown the gRPC server must
|
||||
// stop accepting new streams AND cancel every active stream so the
|
||||
// client observes a clean Cancelled (not a silent stream that only
|
||||
// times out via keepalive). Program.cs registers
|
||||
@@ -192,6 +203,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Contains("shutting", ex.Status.Detail, StringComparison.OrdinalIgnoreCase);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that cancelling all streams a second time has no further effect.</summary>
|
||||
[Fact]
|
||||
public void Host017_CancelAllStreams_IsIdempotent()
|
||||
{
|
||||
@@ -206,6 +218,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.ActiveStreamCount);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a stream subscribes to the stream manager and is removed from it afterwards.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SubscribesAndRemovesFromStreamManager()
|
||||
{
|
||||
@@ -231,6 +245,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
_subscriber.Received(1).RemoveSubscriber(Arg.Any<IActorRef>());
|
||||
}
|
||||
|
||||
/// <summary>Verifies that published events are written to the response stream.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task WritesEventsToResponseStream()
|
||||
{
|
||||
@@ -275,11 +291,13 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await streamTask;
|
||||
}
|
||||
|
||||
// --- SubscribeSite (site-wide, alarm-only aggregated stream, plan #10 T2) ---
|
||||
// --- SubscribeSite (site-wide, alarm-only aggregated stream) ---
|
||||
|
||||
private static SiteStreamRequest MakeSiteRequest(string correlationId = "site-corr-1")
|
||||
=> new() { CorrelationId = correlationId };
|
||||
|
||||
/// <summary>Verifies that a site subscription subscribes to site alarms and is removed on cancellation.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SubscribeSite_SubscribesSiteAlarmsAndRemovesOnCancel()
|
||||
{
|
||||
@@ -307,6 +325,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.ActiveStreamCount);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a site subscription rejects an unsafe correlation id.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SubscribeSite_RejectsUnsafeCorrelationId()
|
||||
{
|
||||
@@ -323,6 +343,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.ActiveStreamCount);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a site subscription relays an alarm state change as an alarm state update.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SubscribeSite_RelaysAlarmStateChangedAsAlarmStateUpdate()
|
||||
{
|
||||
@@ -371,6 +393,9 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await streamTask;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a correlation id that is not safe as an actor name is rejected.</summary>
|
||||
/// <param name="badCorrelationId">A correlation id that is not safe to use as an actor name.</param>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Theory]
|
||||
[InlineData("corr/with/slash")]
|
||||
[InlineData("corr with space")]
|
||||
@@ -378,7 +403,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
[InlineData("$weird")]
|
||||
public async Task RejectsCorrelationIdThatIsNotActorNameSafe(string badCorrelationId)
|
||||
{
|
||||
// Communication-014 regression: a public gRPC SubscribeInstance must not feed
|
||||
// Regression: a public gRPC SubscribeInstance must not feed
|
||||
// an untrusted correlation_id straight into an Akka actor name. An unsafe id
|
||||
// must be rejected cleanly with InvalidArgument rather than escaping as an
|
||||
// unhandled InvalidActorNameException.
|
||||
@@ -395,6 +420,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.ActiveStreamCount);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a correlation id that is safe as an actor name is accepted.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AcceptsActorNameSafeCorrelationId()
|
||||
{
|
||||
@@ -415,10 +442,12 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await streamTask;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that when subscribing throws, the relay actor is stopped and the active stream entry is removed.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Comm021_SubscribeThrows_StopsRelayActorAndRemovesActiveStreamEntry()
|
||||
{
|
||||
// Communication-021 regression: SubscribeInstance creates a StreamRelayActor
|
||||
// Regression: SubscribeInstance creates a StreamRelayActor
|
||||
// and registers an _activeStreams entry BEFORE calling _streamSubscriber.Subscribe.
|
||||
// If Subscribe throws (e.g. stale instance, site runtime shutting down) and the
|
||||
// pre-fix code lets the throw escape without the wrapping try, the relay actor
|
||||
@@ -449,6 +478,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
subscriber.DidNotReceive().RemoveSubscriber(Arg.Any<IActorRef>());
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the active subscribers gauge rises to one on connect and returns to zero on cancellation.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SiteStreamSubscribersActiveGauge_GoesToOneOnConnect_AndBackToZeroOnCancel()
|
||||
{
|
||||
@@ -512,6 +543,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
AwaitAssert(() => Assert.Equal(baseline, ReadGauge()), TimeSpan.FromSeconds(5));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that marking the server ready allows streams to be created.</summary>
|
||||
[Fact]
|
||||
public void SetReady_AllowsStreamCreation()
|
||||
{
|
||||
@@ -540,8 +572,9 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.True(condition(), $"Condition not met within {timeoutMs}ms");
|
||||
}
|
||||
|
||||
// ── WP2.3: the site-wide alarm feed gets its OWN, larger send channel ──
|
||||
// ── The site-wide alarm feed gets its OWN, larger send channel ──
|
||||
|
||||
/// <summary>Verifies that the site alarm stream gets its own channel, larger than the debug view channel.</summary>
|
||||
[Fact]
|
||||
public void SiteAlarmStream_HasItsOwnLargerChannel_ThanTheDebugView()
|
||||
{
|
||||
@@ -556,6 +589,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.True(server.SiteAlarmChannelCapacity > server.InstanceChannelCapacity);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that channel capacities are bound from options and never drop below one.</summary>
|
||||
[Fact]
|
||||
public void ChannelCapacities_AreBoundFromOptions_AndFloorAtOne()
|
||||
{
|
||||
@@ -581,6 +615,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(1, degenerate.SiteAlarmChannelCapacity);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the dropped stream event count starts at zero.</summary>
|
||||
[Fact]
|
||||
public void DroppedStreamEventCount_StartsAtZero()
|
||||
{
|
||||
@@ -590,6 +625,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(0, server.DroppedStreamEventCount);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a duplicate replacement cancels the replaced stream without disposing its cancellation token source.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task DuplicateReplacement_CancelsTheReplacedStream_WithoutDisposingItsCts()
|
||||
{
|
||||
@@ -653,6 +690,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
|
||||
// ── R2: gRPC event batching, and its negotiation ────────────────────────────
|
||||
|
||||
/// <summary>Verifies that batch options are bound from configuration and degenerate values are clamped.</summary>
|
||||
[Fact]
|
||||
public void BatchOptions_AreBoundFromOptions_AndClampDegenerateValues()
|
||||
{
|
||||
@@ -674,6 +712,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
Assert.Equal(TimeSpan.Zero, degenerate.StreamBatchWindow);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a subscription that did not negotiate batching never receives a batch frame.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task UnnegotiatedSubscription_NeverEmitsABatchFrame()
|
||||
{
|
||||
@@ -704,6 +744,8 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
GC.KeepAlive(server);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a batching subscription coalesces a backlog into fewer frames than events.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task NegotiatedSubscription_CoalescesABacklogIntoFewerFramesThanEvents()
|
||||
{
|
||||
@@ -733,13 +775,15 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
$"batching produced {frames.Count} frames for {burst} events — no coalescing happened");
|
||||
Assert.Contains(frames, f => f.EventCase == SiteStreamEvent.EventOneofCase.Batch);
|
||||
|
||||
// Order is preserved end to end: the values arrive 0..burst-1 exactly once each.
|
||||
// Order is preserved end to end: the values arrive 0 to burst minus 1 exactly once each.
|
||||
var values = frames.SelectMany(FlattenAttributeValues).ToArray();
|
||||
Assert.Equal(Enumerable.Range(0, burst).Select(i => i.ToString()), values);
|
||||
|
||||
GC.KeepAlive(server);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the batch size histogram is recorded only for streams that negotiated batching.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task BatchSizeHistogram_IsRecordedOnlyForNegotiatedStreams()
|
||||
{
|
||||
@@ -795,7 +839,7 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
}
|
||||
}
|
||||
|
||||
// ── P3-5: the concurrency cap must never refuse a REPLACEMENT ───────────────
|
||||
// ── The concurrency cap must never refuse a REPLACEMENT ───────────────
|
||||
|
||||
/// <summary>
|
||||
/// A <see cref="ServerCallContext"/> whose <see cref="ServerCallContext.CancellationToken"/>
|
||||
@@ -811,24 +855,38 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
private readonly Metadata _trailers = new();
|
||||
private readonly Dictionary<object, object> _userState = new();
|
||||
|
||||
/// <summary>Initializes a new instance of the <c>GatedServerCallContext</c> class.</summary>
|
||||
/// <param name="token">The cancellation token the context exposes.</param>
|
||||
/// <param name="onCancellationTokenRead">Callback invoked when the cancellation token is read.</param>
|
||||
public GatedServerCallContext(CancellationToken token, Action onCancellationTokenRead)
|
||||
{
|
||||
_token = token;
|
||||
_onCancellationTokenRead = onCancellationTokenRead;
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
protected override string MethodCore => "/sitestream.SiteStreamService/SubscribeInstance";
|
||||
/// <inheritdoc />
|
||||
protected override string HostCore => "localhost";
|
||||
/// <inheritdoc />
|
||||
protected override string PeerCore => "ipv4:127.0.0.1:0";
|
||||
/// <inheritdoc />
|
||||
protected override DateTime DeadlineCore => DateTime.MaxValue;
|
||||
/// <inheritdoc />
|
||||
protected override Metadata RequestHeadersCore => Metadata.Empty;
|
||||
/// <inheritdoc />
|
||||
protected override Metadata ResponseTrailersCore => _trailers;
|
||||
/// <inheritdoc />
|
||||
protected override GrpcStatus StatusCore { get; set; }
|
||||
/// <inheritdoc />
|
||||
protected override WriteOptions? WriteOptionsCore { get; set; }
|
||||
/// <inheritdoc />
|
||||
protected override AuthContext AuthContextCore =>
|
||||
new(null, new Dictionary<string, List<AuthProperty>>());
|
||||
/// <inheritdoc />
|
||||
protected override IDictionary<object, object> UserStateCore => _userState;
|
||||
|
||||
/// <inheritdoc />
|
||||
protected override CancellationToken CancellationTokenCore
|
||||
{
|
||||
get
|
||||
@@ -838,17 +896,21 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
}
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
protected override ContextPropagationToken CreatePropagationTokenCore(
|
||||
ContextPropagationOptions? options) => throw new NotSupportedException();
|
||||
|
||||
/// <inheritdoc />
|
||||
protected override Task WriteResponseHeadersAsyncCore(Metadata responseHeaders) =>
|
||||
Task.CompletedTask;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a duplicate reconnect at the cap is not refused and leaves exactly one live stream.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AtCapOvershoot_DuplicateReconnect_IsNotRefused_AndLeavesExactlyOneLiveStream()
|
||||
{
|
||||
// P3-5. The duplicate-replacement path cancels the incumbent; the cap check then had
|
||||
// The duplicate-replacement path cancels the incumbent; the cap check then had
|
||||
// to decide whether the REPLACEMENT may take its place. Checking `Count >= max` after
|
||||
// the removal is right at exactly the cap but wrong above it — and above it is
|
||||
// reachable, because the cap check is documented check-then-act: two subscribes that
|
||||
@@ -913,10 +975,12 @@ public class SiteStreamGrpcServerTests : TestKit
|
||||
await WaitForConditionAsync(() => server.ActiveStreamCount == 0);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a genuinely new subscriber at the cap is still refused and the incumbent survives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AtCap_AGenuinelyNewSubscriber_IsStillRefused_AndTheIncumbentSurvives()
|
||||
{
|
||||
// The other half of P3-5: excluding replacements from the cap must NOT weaken the cap
|
||||
// The other half of that rule: excluding replacements from the cap must NOT weaken the cap
|
||||
// for a new correlation id, and a refusal must leave the existing streams untouched
|
||||
// (TryRemove found nothing, so nothing was cancelled before the throw).
|
||||
var server = CreateServer(maxStreams: 1);
|
||||
|
||||
Reference in New Issue
Block a user