docs: complete XML-doc coverage and strip internal tracking IDs from code comments
ci / java (push) Successful in 5m51s
ci / portable (push) Successful in 6m43s

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:
Joseph Doherty
2026-07-10 06:15:47 -04:00
parent abb0930359
commit b86c6bb47f
74 changed files with 393 additions and 298 deletions
@@ -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