dohertj2/ScadaBridge
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(comments): strip internal task/milestone/bundle bookkeeping from code comments

Browse Source 
Remove project bookkeeping citations from shipped code comments across the
solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/
issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels,
and C/D/K/S/T phase labels.

Comment text only — no code logic, string/log literals, or XML-doc structure
changed. Genuine descriptions are preserved (only the citation is stripped),
and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365,
UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker
TaskReferenceInComment / TrackingReferenceInComment checks plus targeted
grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
Joseph Doherty
2026-07-07 11:03:26 -04:00
parent 67005ca4c0
commit 9cff87fe85
435 changed files with 2338 additions and 2547 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.InboundAPI/Middleware/AuditWriteMiddleware.cs
+19 -19
View File
@@ -15,7 +15,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Middleware;
/// <summary>
/// Audit Log #23 (M4 Bundle D, T7) — emits one <see cref="AuditChannel.ApiInbound"/>
/// Emits one <see cref="AuditChannel.ApiInbound"/>
/// row per inbound API request via <see cref="ICentralAuditWriter"/> covering the
/// full set of response shapes:
///
@@ -39,7 +39,7 @@ namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Middleware;
/// for Bearer API-key callers), so the handler stashes the resolved API key name on
/// <see cref="HttpContext.Items"/> under <see cref="AuditActorItemKey"/> after
/// <c>IApiKeyVerifier.VerifyAsync</c> succeeds. The middleware reads it in
/// its <c>finally</c> block. Phase 3: when no API-key name is stashed, the actor is
/// its <c>finally</c> block. When no API-key name is stashed, the actor is
/// sourced from the authenticated <em>interactive</em> principal via
/// <see cref="IAuditActorAccessor"/> (a cookie/LDAP-authenticated inbound user,
/// keyed off the canonical username claim). On auth failures (401/403) the actor is
@@ -80,7 +80,7 @@ public sealed class AuditWriteMiddleware
public const string AuditActorItemKey = "ZB.MOM.WW.ScadaBridge.InboundAPI.AuditActor";
/// <summary>
/// Audit Log #23 (ParentExecutionId): <see cref="HttpContext.Items"/> key under
/// ParentExecutionId: <see cref="HttpContext.Items"/> key under
/// which this middleware stashes the inbound request's per-request
/// <c>ExecutionId</c> (a <see cref="Guid"/>) at the very start of the request.
/// The id is minted ONCE and shared: the endpoint handler reads it to thread it
@@ -106,14 +106,14 @@ public sealed class AuditWriteMiddleware
/// <param name="logger">Logger for this middleware.</param>
/// <param name="options">Live-reloadable audit log options, read per-request.</param>
/// <param name="actorAccessor">
/// Phase 3 (optional): resolves the audit <see cref="AuditEvent.Actor"/> from the
/// Resolves the audit <see cref="AuditEvent.Actor"/> from the
/// authenticated principal on a cookie/LDAP-authenticated inbound request. Optional
/// so existing tests (and any composition without the accessor registered) still
/// construct the middleware; when absent, actor resolution falls back to the
/// stashed API-key name only.
/// </param>
/// <param name="ceilingHitsCounter">
/// M5.3 (T7, optional): incremented whenever an inbound request or response
/// Incremented whenever an inbound request or response
/// body is truncated at <see cref="AuditLogOptions.InboundMaxBytes"/>. Optional
/// so existing tests and composition roots without the central health snapshot
/// wired still construct without the counter; a NoOp is used when absent.
@@ -149,7 +149,7 @@ public sealed class AuditWriteMiddleware
var opts = _options.CurrentValue;
var cap = opts.InboundMaxBytes;
// Audit Log #23 (ParentExecutionId): mint the inbound request's per-request
// ParentExecutionId: mint the inbound request's per-request
// ExecutionId ONCE, here at the start of the request, and stash it on
// HttpContext.Items. Two consumers share this single id:
// (a) the endpoint handler reads it to thread onto a routed
@@ -166,7 +166,7 @@ public sealed class AuditWriteMiddleware
// of the pipeline for us — but we also rewind to position 0 after our
// own read so the very next reader starts from the top.
//
// InboundAPI-019: skip EnableBuffering for bodyless requests (a known
// Skip EnableBuffering for bodyless requests (a known
// empty Content-Length or a method that conventionally carries no body —
// GET / HEAD / DELETE / TRACE / OPTIONS). The FileBufferingReadStream
// wrapper EnableBuffering installs allocates an internal buffer regardless
@@ -176,7 +176,7 @@ public sealed class AuditWriteMiddleware
// returns (null, false) for the bodyless case anyway, so the audit row
// is unchanged.
//
// M5.3 (T7): check if the matched method/target has SkipBodyCapture set.
// Check if the matched method/target has SkipBodyCapture set.
// The route value is resolved BEFORE the pipeline runs (route matching
// has already bound {methodName} at this point), so we can skip the
// EnableBuffering allocation and body read up front.
@@ -224,7 +224,7 @@ public sealed class AuditWriteMiddleware
// original sink; this just pulls back the bounded UTF-8 string.
ctx.Response.Body = originalResponseBody;
var (capturedResponseBody, capturedResponseTruncated) = captureStream.GetCapturedBody();
// M5.3 (T7): if SkipBodyCapture is set, discard the captured response
// If SkipBodyCapture is set, discard the captured response
// body (the request body was never captured above). The row + headers
// still emit with null RequestSummary / ResponseSummary.
// Truncation flags are also cleared so ceiling-hit counter is not
@@ -279,14 +279,14 @@ public sealed class AuditWriteMiddleware
var actor = isAuthFailure ? null : ResolveActor(ctx);
var methodName = ResolveMethodName(ctx);
// M5.3 (T7): increment the ceiling-hits counter once per request
// Increment the ceiling-hits counter once per request
// that hit the cap on EITHER the request or response body.
if (requestTruncated || responseTruncated)
{
try { _ceilingHitsCounter.Increment(); } catch { /* swallow per §7 */ }
}
// M5.3 (T7): capture request headers into Extra JSON alongside the
// Capture request headers into Extra JSON alongside the
// existing remoteIp / userAgent provenance fields. The header
// collection is run through the SAME header-redaction list
// (AuditLogOptions.HeaderRedactList) that the ScadaBridgeAuditRedactor
@@ -325,7 +325,7 @@ public sealed class AuditWriteMiddleware
occurredAtUtc: DateTime.UtcNow,
actor: actor,
target: methodName,
// Audit Log #23: the per-request execution id minted ONCE at the
// The per-request execution id minted ONCE at the
// start of the request (InvokeAsync) and stashed on
// HttpContext.Items. The same id is threaded onto a routed
// RouteToCallRequest.ParentExecutionId by the endpoint handler,
@@ -347,7 +347,7 @@ public sealed class AuditWriteMiddleware
// Central direct-write — no site-local forwarding state (not a
// canonical field).
// InboundAPI-018: fire-and-forget the writer so the user-facing
// Fire-and-forget the writer so the user-facing
// response stays non-blocking (alog.md §13 — audit emission must
// NEVER abort or delay the user request), but observe the returned
// Task so an asynchronous fault is logged instead of vanishing into
@@ -368,7 +368,7 @@ public sealed class AuditWriteMiddleware
}
/// <summary>
/// InboundAPI-018: observe the audit writer's returned <see cref="Task"/>
/// Observe the audit writer's returned <see cref="Task"/>
/// so a fault that surfaces ASYNCHRONOUSLY (e.g. a DB timeout deep in the
/// central audit pipeline) is logged at Warning rather than dropped into
/// <see cref="TaskScheduler.UnobservedTaskException"/>. Stays
@@ -398,7 +398,7 @@ public sealed class AuditWriteMiddleware
}
/// <summary>
/// InboundAPI-019: decides whether the request is likely to carry a body, so the
/// Decides whether the request is likely to carry a body, so the
/// caller can skip <see cref="HttpRequestRewindExtensions.EnableBuffering(HttpRequest)"/>
/// (and the associated <c>FileBufferingReadStream</c> allocation) on requests that
/// definitely won't have one. Returns <c>true</c> when <see cref="HttpRequest.ContentLength"/>
@@ -533,7 +533,7 @@ public sealed class AuditWriteMiddleware
}
/// <summary>
/// Audit Log #23 (ParentExecutionId): reads the inbound request's per-request
/// ParentExecutionId: reads the inbound request's per-request
/// <c>ExecutionId</c> that <see cref="InvokeAsync"/> minted and stashed on
/// <see cref="HttpContext.Items"/> under <see cref="InboundExecutionIdItemKey"/>.
/// Throws <see cref="InvalidOperationException"/> if the slot is absent — for a
@@ -563,7 +563,7 @@ public sealed class AuditWriteMiddleware
/// <see cref="HttpContext.Items"/> after successful key auth (the
/// key-authenticated path — the canonical identity of an API-key caller);</description></item>
/// <item><description>otherwise the authenticated <em>interactive</em> principal
/// resolved through <see cref="IAuditActorAccessor"/> (Phase 3 — a
/// resolved through <see cref="IAuditActorAccessor"/> (a
/// cookie/LDAP-authenticated inbound user, sourced from the canonical username
/// claim). The accessor reads the ambient <see cref="HttpContext.User"/>, so the
/// fall-through here only fires when no API-key name was stashed;</description></item>
@@ -571,7 +571,7 @@ public sealed class AuditWriteMiddleware
/// principal back as an actor.</description></item>
/// </list>
/// The accessor is optional (constructor default <c>null</c>); when absent only
/// the stashed API-key name is consulted, preserving the pre-Phase-3 behaviour.
/// the stashed API-key name is consulted, preserving the previous behaviour.
/// </summary>
private string? ResolveActor(HttpContext ctx)
{
@@ -582,7 +582,7 @@ public sealed class AuditWriteMiddleware
return name;
}
// Phase 3: an interactive cookie/LDAP-authenticated inbound user records
// An interactive cookie/LDAP-authenticated inbound user records
// their real identity as Actor. Returns null for the key-authenticated
// and auth-failure paths (no authenticated interactive principal), so the
// existing API-key/auth-failure behaviour is preserved.