docs(comments): strip internal task/milestone/bundle bookkeeping from code comments
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
@@ -12,7 +12,7 @@ using ZB.MOM.WW.ScadaBridge.StoreAndForward;
|
||||
namespace ZB.MOM.WW.ScadaBridge.ExternalSystemGateway;
|
||||
|
||||
/// <summary>
|
||||
/// WP-9: Database access from scripts.
|
||||
/// Database access from scripts.
|
||||
/// Database.Connection("name") — returns ADO.NET SqlConnection (connection pooling).
|
||||
/// Database.CachedWrite("name", "sql", params) — submits to S&F engine.
|
||||
/// </summary>
|
||||
@@ -58,7 +58,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
{
|
||||
// OpenAsync failed (unreachable server, bad credentials, cancellation) —
|
||||
// dispose the just-created connection before the exception propagates so
|
||||
// it is not leaked (ExternalSystemGateway-010).
|
||||
// it is not leaked.
|
||||
await connection.DisposeAsync();
|
||||
throw;
|
||||
}
|
||||
@@ -97,12 +97,12 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
throw new InvalidOperationException("Store-and-forward service not available for cached writes");
|
||||
}
|
||||
|
||||
// M2.3 (#7): attempt the write IMMEDIATELY and classify the outcome,
|
||||
// mirroring ExternalSystemClient.CachedCallAsync. The pre-M2.3 behaviour
|
||||
// enqueued every write unconditionally and the S&F retry sweep then
|
||||
// retried ALL failures forever — a permanent SQL error (constraint,
|
||||
// syntax, permission) was never returned to the script and spun in the
|
||||
// buffer indefinitely. Now:
|
||||
// Attempt the write IMMEDIATELY and classify the outcome, mirroring
|
||||
// ExternalSystemClient.CachedCallAsync. The previous behaviour enqueued
|
||||
// every write unconditionally and the S&F retry sweep then retried ALL
|
||||
// failures forever — a permanent SQL error (constraint, syntax,
|
||||
// permission) was never returned to the script and spun in the buffer
|
||||
// indefinitely. Now:
|
||||
// * success -> Delivered, NOT buffered;
|
||||
// * PermanentDatabaseException -> Failed synchronously, NOT buffered;
|
||||
// * TransientDatabaseException -> buffered to S&F for retry.
|
||||
@@ -142,7 +142,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
Parameters = parameters
|
||||
});
|
||||
|
||||
// ExternalSystemGateway-015: the entity's MaxRetries is a non-nullable int
|
||||
// The entity's MaxRetries is a non-nullable int
|
||||
// whose default is 0, and the Store-and-Forward engine interprets a stored
|
||||
// MaxRetries of 0 as "no limit" (retry forever) — see
|
||||
// StoreAndForwardMessage.MaxRetries ("0 = no limit") and the retry-sweep
|
||||
@@ -157,28 +157,26 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
originInstanceName,
|
||||
definition.MaxRetries > 0 ? definition.MaxRetries : null,
|
||||
definition.RetryDelay > TimeSpan.Zero ? definition.RetryDelay : null,
|
||||
// M2.3 (#7): attemptImmediateDelivery: false — this method already
|
||||
// attemptImmediateDelivery: false — this method already
|
||||
// made the write attempt above (the transient-classified failure is
|
||||
// exactly why we are buffering). Letting EnqueueAsync re-invoke the
|
||||
// delivery handler would execute the same write a second time —
|
||||
// mirrors ExternalSystemClient.CachedCallAsync.
|
||||
attemptImmediateDelivery: false,
|
||||
// Audit Log #23 (M3): pin the S&F message id to the
|
||||
// TrackedOperationId so the retry loop (Bundle E Tasks E4/E5) can
|
||||
// Pin the S&F message id to the
|
||||
// TrackedOperationId so the retry loop can
|
||||
// read it back via StoreAndForwardMessage.Id and emit per-attempt +
|
||||
// terminal cached-write telemetry. Null -> S&F mints its own GUID
|
||||
// (legacy pre-M3 behaviour).
|
||||
// (legacy behaviour).
|
||||
messageId: trackedOperationId?.ToString(),
|
||||
// Audit Log #23 (ExecutionId Task 4): thread the originating script
|
||||
// execution's ExecutionId + SourceScript onto the buffered row so
|
||||
// the retry-loop cached-write audit rows carry the same provenance
|
||||
// the script-side cached rows do.
|
||||
// Thread the originating script execution's ExecutionId + SourceScript
|
||||
// onto the buffered row so the retry-loop cached-write audit rows carry
|
||||
// the same provenance the script-side cached rows do.
|
||||
executionId: executionId,
|
||||
sourceScript: sourceScript,
|
||||
// Audit Log #23 (ParentExecutionId Task 6): thread the spawning
|
||||
// inbound-API request's ExecutionId onto the buffered row so the
|
||||
// retry-loop cached-write audit rows correlate back to the
|
||||
// cross-execution chain. Null for a non-routed run.
|
||||
// Thread the spawning inbound-API request's ExecutionId onto the
|
||||
// buffered row so the retry-loop cached-write audit rows correlate
|
||||
// back to the cross-execution chain. Null for a non-routed run.
|
||||
parentExecutionId: parentExecutionId);
|
||||
|
||||
// Buffered for retry — mirrors the API path's WasBuffered=true result.
|
||||
@@ -186,17 +184,17 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WP-9/10: Delivers a buffered CachedDbWrite during a store-and-forward retry
|
||||
/// Delivers a buffered CachedDbWrite during a store-and-forward retry
|
||||
/// sweep — executes the SQL against the named connection.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// M2.3 (#7): the outcome is classified, mirroring
|
||||
/// The outcome is classified, mirroring
|
||||
/// <see cref="ExternalSystemClient.DeliverBufferedAsync"/>. Returns
|
||||
/// <c>false</c> — so the S&F engine PARKS the message — when the
|
||||
/// connection no longer exists, the payload is unreadable, or the SQL fails
|
||||
/// with a PERMANENT error (constraint / syntax / permission). A TRANSIENT SQL
|
||||
/// error (<see cref="TransientDatabaseException"/>) propagates so the engine
|
||||
/// retries. The pre-M2.3 code rethrew on ANY SQL error, so a permanent
|
||||
/// retries. The previous code rethrew on ANY SQL error, so a permanent
|
||||
/// failure on the retry path looped forever.
|
||||
/// </remarks>
|
||||
/// <param name="message">The buffered store-and-forward message to deliver.</param>
|
||||
@@ -206,7 +204,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
public async Task<bool> DeliverBufferedAsync(
|
||||
StoreAndForwardMessage message, CancellationToken cancellationToken = default)
|
||||
{
|
||||
// ExternalSystemGateway-018: a malformed (not just empty/null-fielded)
|
||||
// A malformed (not just empty/null-fielded)
|
||||
// PayloadJson would otherwise throw `JsonException` here, which the S&F
|
||||
// engine treats as a transient failure and retries forever (poison
|
||||
// message). Re-running the same deserialization against the same payload
|
||||
@@ -280,7 +278,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
new Dictionary<string, object?>();
|
||||
|
||||
/// <summary>
|
||||
/// M2.3 (#7): executes a parameterised SQL write against the given connection
|
||||
/// Executes a parameterised SQL write against the given connection
|
||||
/// string and classifies the outcome into
|
||||
/// <see cref="TransientDatabaseException"/> / <see cref="PermanentDatabaseException"/>,
|
||||
/// mirroring the ordered catches of
|
||||
@@ -313,7 +311,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
IReadOnlyDictionary<string, object?> parameters,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// M2.3 (#7) code-review fix: the catch ordering MIRRORS
|
||||
// The catch ordering MIRRORS
|
||||
// ExternalSystemClient.InvokeHttpAsync exactly so the SQL path classifies
|
||||
// a live outage the same way the HTTP path does:
|
||||
// 1. caller-requested cancellation propagates UNCHANGED (never a "DB error");
|
||||
@@ -338,7 +336,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
}
|
||||
catch (SqlException ex)
|
||||
{
|
||||
// [2] ExternalSystemGateway-025: a caller-token cancellation can surface
|
||||
// [2] A caller-token cancellation can surface
|
||||
// from the SQL driver as a SqlException (a mid-flight cancel), not an
|
||||
// OperationCanceledException, so the [1] filter above never sees it.
|
||||
// Re-check the caller's token at the TOP of this block so such a cancel
|
||||
@@ -366,7 +364,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// M2.3 (#7): the raw ADO.NET write — opens the connection, builds the
|
||||
/// The raw ADO.NET write — opens the connection, builds the
|
||||
/// command, and executes it. Marked <c>internal virtual</c> so tests can throw
|
||||
/// RAW outage-shaped exceptions (e.g. <see cref="InvalidOperationException"/>,
|
||||
/// <see cref="System.Net.Sockets.SocketException"/>) through the PRODUCTION
|
||||
@@ -399,7 +397,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
// ExternalSystemGateway-020: a JSON number that does not fit in Int64 must
|
||||
// A JSON number that does not fit in Int64 must
|
||||
// prefer decimal over double — a script's decimal SQL parameter is
|
||||
// serialised as JSON without a type tag, and downcasting it to double on
|
||||
// the cached-write retry path silently loses precision (e.g.
|
||||
@@ -437,7 +435,7 @@ public class DatabaseGateway : IDatabaseGateway
|
||||
string connectionName,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// ExternalSystemGateway-011: name-keyed repository lookup instead of
|
||||
// Name-keyed repository lookup instead of
|
||||
// fetch-all-then-filter — connection definitions are resolved on every
|
||||
// cached write / connection request, so the repository performs an indexed
|
||||
// query rather than loading every connection into memory.
|
||||
|
||||
Reference in New Issue
Block a user