docs(src): add missing XML docs and strip tracking-ID comments
Sweep of 203 source files resolving CommentChecker findings: add <summary>/<param>/<returns>/<inheritdoc> where missing, and remove resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN, Task N) from code comments. Comment/doc-only — no logic changes. Server+Tests build clean under TreatWarningsAsErrors.
This commit is contained in:
@@ -16,10 +16,7 @@ public sealed class ConstraintEnforcer(
|
||||
IGalaxyHierarchyCache cache,
|
||||
IAuditWriter auditWriter) : IConstraintEnforcer
|
||||
{
|
||||
/// <summary>Checks read constraints on a tag address.</summary>
|
||||
/// <param name="identity">The API key identity to check constraints for.</param>
|
||||
/// <param name="tagAddress">Tag address to validate.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <inheritdoc />
|
||||
public Task<ConstraintFailure?> CheckReadTagAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
string tagAddress,
|
||||
@@ -34,12 +31,7 @@ public sealed class ConstraintEnforcer(
|
||||
return Task.FromResult(CheckReadTarget(constraints, tagAddress));
|
||||
}
|
||||
|
||||
/// <summary>Checks read constraints on a server and item handle.</summary>
|
||||
/// <param name="identity">The API key identity to check constraints for.</param>
|
||||
/// <param name="session">The gateway session containing handle registrations.</param>
|
||||
/// <param name="serverHandle">The MXAccess server handle.</param>
|
||||
/// <param name="itemHandle">The MXAccess item handle.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <inheritdoc />
|
||||
public Task<ConstraintFailure?> CheckReadHandleAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
GatewaySession session,
|
||||
@@ -61,12 +53,7 @@ public sealed class ConstraintEnforcer(
|
||||
return Task.FromResult(CheckReadTarget(constraints, registration.TagAddress));
|
||||
}
|
||||
|
||||
/// <summary>Checks write constraints on a server and item handle.</summary>
|
||||
/// <param name="identity">The API key identity to check constraints for.</param>
|
||||
/// <param name="session">The gateway session containing handle registrations.</param>
|
||||
/// <param name="serverHandle">The MXAccess server handle.</param>
|
||||
/// <param name="itemHandle">The MXAccess item handle.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <inheritdoc />
|
||||
public Task<ConstraintFailure?> CheckWriteHandleAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
GatewaySession session,
|
||||
@@ -115,18 +102,7 @@ public sealed class ConstraintEnforcer(
|
||||
return Task.FromResult<ConstraintFailure?>(null);
|
||||
}
|
||||
|
||||
/// <summary>Records a constraint denial audit entry.</summary>
|
||||
/// <param name="identity">The API key identity that was denied.</param>
|
||||
/// <param name="commandKind">The command type (e.g., read, write).</param>
|
||||
/// <param name="target">The target being accessed (tag address or handle).</param>
|
||||
/// <param name="failure">The constraint failure details.</param>
|
||||
/// <param name="correlationId">
|
||||
/// The per-request client correlation id, if any. Persisted as the audit record's typed
|
||||
/// <c>CorrelationId</c> when it parses as a GUID; a non-GUID value leaves that column null.
|
||||
/// The raw string is always preserved in <c>DetailsJson["clientCorrelationId"]</c> so a
|
||||
/// non-GUID id (e.g. from Rust/Python/Java clients) is never silently lost.
|
||||
/// </param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <inheritdoc />
|
||||
public async Task RecordDenialAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
string commandKind,
|
||||
@@ -135,8 +111,8 @@ public sealed class ConstraintEnforcer(
|
||||
string? correlationId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Emit a canonical Denied AuditEvent directly through the best-effort IAuditWriter
|
||||
// (Task 2.3 #6): structured Target ("<commandKind>:<target>") and a richer DetailsJson
|
||||
// Emit a canonical Denied AuditEvent directly through the best-effort IAuditWriter:
|
||||
// structured Target ("<commandKind>:<target>") and a richer DetailsJson
|
||||
// envelope carrying constraint/message/commandKind/target.
|
||||
AuditEvent auditEvent = new()
|
||||
{
|
||||
|
||||
@@ -8,7 +8,9 @@ namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
|
||||
public sealed class GatewayBrowseScopeProvider(IGatewayRequestIdentityAccessor identityAccessor)
|
||||
: IGalaxyBrowseScopeProvider
|
||||
{
|
||||
/// <inheritdoc />
|
||||
/// <summary>Resolves the Galaxy browse subtrees the calling API key is scoped to, from the ambient request identity.</summary>
|
||||
/// <param name="context">The gRPC server call context for the in-flight browse request.</param>
|
||||
/// <returns>The caller's configured browse subtrees, or <see langword="null"/>/empty when the caller is unscoped (full hierarchy).</returns>
|
||||
public IReadOnlyList<string>? ResolveBrowseSubtrees(ServerCallContext context)
|
||||
{
|
||||
// Invariant: the caller identity is the ambient one pushed by
|
||||
|
||||
+2
-4
@@ -6,12 +6,10 @@ public sealed class GatewayRequestIdentityAccessor : IGatewayRequestIdentityAcce
|
||||
{
|
||||
private readonly AsyncLocal<ApiKeyIdentity?> currentIdentity = new();
|
||||
|
||||
/// <summary>Gets the current request identity.</summary>
|
||||
/// <inheritdoc />
|
||||
public ApiKeyIdentity? Current => currentIdentity.Value;
|
||||
|
||||
/// <summary>Sets the current identity and returns a scope that restores the previous identity.</summary>
|
||||
/// <param name="identity">The identity to push.</param>
|
||||
/// <returns>Disposable scope.</returns>
|
||||
/// <inheritdoc />
|
||||
public IDisposable Push(ApiKeyIdentity identity)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(identity);
|
||||
|
||||
+1
@@ -13,6 +13,7 @@ public static class GrpcAuthorizationServiceCollectionExtensions
|
||||
/// Registers gRPC authorization middleware and scope resolver.
|
||||
/// </summary>
|
||||
/// <param name="services">Service collection to register dependencies into.</param>
|
||||
/// <returns>The same service collection, for chaining.</returns>
|
||||
public static IServiceCollection AddGatewayGrpcAuthorization(this IServiceCollection services)
|
||||
{
|
||||
services.AddSingleton<GatewayGrpcScopeResolver>();
|
||||
|
||||
@@ -9,6 +9,7 @@ public interface IConstraintEnforcer
|
||||
/// <param name="identity">The API key identity.</param>
|
||||
/// <param name="tagAddress">Tag address to check.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
||||
Task<ConstraintFailure?> CheckReadTagAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
string tagAddress,
|
||||
@@ -20,6 +21,7 @@ public interface IConstraintEnforcer
|
||||
/// <param name="serverHandle">The MXAccess server handle.</param>
|
||||
/// <param name="itemHandle">The MXAccess item handle.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
||||
Task<ConstraintFailure?> CheckReadHandleAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
GatewaySession session,
|
||||
@@ -33,6 +35,7 @@ public interface IConstraintEnforcer
|
||||
/// <param name="serverHandle">The MXAccess server handle.</param>
|
||||
/// <param name="itemHandle">The MXAccess item handle.</param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
||||
Task<ConstraintFailure?> CheckWriteHandleAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
GatewaySession session,
|
||||
@@ -50,6 +53,7 @@ public interface IConstraintEnforcer
|
||||
/// <c>CorrelationId</c> when it parses as a GUID; otherwise left null.
|
||||
/// </param>
|
||||
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
Task RecordDenialAsync(
|
||||
ApiKeyIdentity? identity,
|
||||
string commandKind,
|
||||
|
||||
+1
@@ -10,5 +10,6 @@ public interface IGatewayRequestIdentityAccessor
|
||||
|
||||
/// <summary>Temporarily pushes an identity onto the scope stack, returning a handle to restore the previous state.</summary>
|
||||
/// <param name="identity">API key identity to push.</param>
|
||||
/// <returns>A disposable handle that restores the previous identity when disposed.</returns>
|
||||
IDisposable Push(ApiKeyIdentity identity);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user