docs: complete XML-doc coverage and strip internal tracking IDs from code comments
Resolve all CommentChecker findings across the gateway server, worker, tests, and .NET client (314 -> 0 real issues): add missing <returns>/<summary>/<param> on public and test members, convert Stream/interface overrides to <inheritdoc/>, and remove internal task/issue tracking IDs (SEC-*, IPC-*, WRK-*, GWC-*, TST-*, Client.Dotnet-*) from shipped code documentation while preserving the design rationale prose. Shipped comments should not carry internal bookkeeping, and complete XML docs keep the analyzer/TreatWarningsAsErrors gate and generated API docs clean. The 6 remaining flags are heuristic false positives (MD5, UTC-4, capacity-1, near-1601) left intact so real documentation is not corrupted. Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW
This commit is contained in:
@@ -14,43 +14,33 @@ public sealed class EventStreamService(
|
||||
GatewayMetrics metrics) : IEventStreamService
|
||||
{
|
||||
/// <inheritdoc />
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This reads the subscriber's lease channel fed by the session's single
|
||||
/// <see cref="SessionEventDistributor"/> pump. The pump owns the single drain of
|
||||
/// the worker event stream and the worker→public mapping (mirroring the former
|
||||
/// <c>ProduceEventsAsync</c>); this loop is the per-subscriber boundary that
|
||||
/// applies the per-RPC filter (<c>AfterWorkerSequence</c>), queue-depth metrics,
|
||||
/// and the backpressure/overflow policy.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The dashboard mirror runs OFF this per-RPC loop. The dashboard is a
|
||||
/// first-class internal subscriber on the session's
|
||||
/// <see cref="SessionEventDistributor"/> (see <c>GatewaySession.StartDashboardMirror</c>),
|
||||
/// so it receives session events even when no gRPC client is streaming. This loop
|
||||
/// does not mirror to the dashboard. One deliberate consequence: the dashboard sees
|
||||
/// RAW session events, not the per-gRPC-subscriber <c>AfterWorkerSequence</c>-filtered
|
||||
/// view this loop applies — the dashboard is a separate LDAP-authenticated monitoring
|
||||
/// view that should see the session's full event activity.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Overflow handling: the distributor's per-subscriber channel is bounded
|
||||
/// and the pump writes non-blocking. When this subscriber's channel is full the pump
|
||||
/// applies the per-subscriber backpressure policy and completes this subscriber's
|
||||
/// channel with a <see cref="SessionManagerException"/>
|
||||
/// (<see cref="SessionManagerErrorCode.EventQueueOverflow"/>). That terminal fault
|
||||
/// surfaces here when the reader's <c>MoveNextAsync</c> throws, and it propagates to
|
||||
/// the gRPC client unchanged. The overflow metric, and (in the legacy
|
||||
/// single-subscriber FailFast case) the session fault + fault metric, are recorded by
|
||||
/// the distributor's overflow handler so the session, the pump, and other subscribers
|
||||
/// are isolated from this subscriber's slowness.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
|
||||
StreamEventsRequest request,
|
||||
string? callerKeyId,
|
||||
[EnumeratorCancellation] CancellationToken cancellationToken)
|
||||
{
|
||||
// This reads the subscriber's lease channel fed by the session's single
|
||||
// SessionEventDistributor pump. The pump owns the single drain of the worker event
|
||||
// stream and the worker->public mapping (mirroring the former ProduceEventsAsync); this
|
||||
// loop is the per-subscriber boundary that applies the per-RPC filter (AfterWorkerSequence),
|
||||
// queue-depth metrics, and the backpressure/overflow policy.
|
||||
//
|
||||
// The dashboard mirror runs OFF this per-RPC loop. The dashboard is a first-class internal
|
||||
// subscriber on the session's SessionEventDistributor (see GatewaySession.StartDashboardMirror),
|
||||
// so it receives session events even when no gRPC client is streaming. This loop does not
|
||||
// mirror to the dashboard. One deliberate consequence: the dashboard sees RAW session events,
|
||||
// not the per-gRPC-subscriber AfterWorkerSequence-filtered view this loop applies — the
|
||||
// dashboard is a separate LDAP-authenticated monitoring view that should see the session's
|
||||
// full event activity.
|
||||
//
|
||||
// Overflow handling: the distributor's per-subscriber channel is bounded and the pump writes
|
||||
// non-blocking. When this subscriber's channel is full the pump applies the per-subscriber
|
||||
// backpressure policy and completes this subscriber's channel with a SessionManagerException
|
||||
// (SessionManagerErrorCode.EventQueueOverflow). That terminal fault surfaces here when the
|
||||
// reader's MoveNextAsync throws, and it propagates to the gRPC client unchanged. The overflow
|
||||
// metric, and (in the legacy single-subscriber FailFast case) the session fault + fault metric,
|
||||
// are recorded by the distributor's overflow handler so the session, the pump, and other
|
||||
// subscribers are isolated from this subscriber's slowness.
|
||||
if (!sessionManager.TryGetSession(request.SessionId, out GatewaySession? session) || session is null)
|
||||
{
|
||||
throw new SessionManagerException(
|
||||
@@ -58,7 +48,7 @@ public sealed class EventStreamService(
|
||||
$"Session {request.SessionId} was not found.");
|
||||
}
|
||||
|
||||
// Owner-scoped attach (TST-02, security control): a session's event stream may be
|
||||
// Owner-scoped attach (security control): a session's event stream may be
|
||||
// attached or reattached ONLY by the API key that opened the session. The detach-grace
|
||||
// and fan-out retention windows are on by default, so without this check any event-scoped
|
||||
// key that learns a session id could attach to another key's retained session and receive
|
||||
|
||||
Reference in New Issue
Block a user