From 5d49cca673f3d6df6f42b6b5c857f2c833062235 Mon Sep 17 00:00:00 2001 From: Loic Sharma Date: Tue, 26 Jan 2021 11:29:50 -0800 Subject: [PATCH 1/4] Rename NuGet package validation interfaces --- .../{IProcessor.cs => INuGetProcessor.cs} | 0 ...nRequest.cs => INuGetValidationRequest.cs} | 7 ++- ...nResult.cs => INuGetValidationResponse.cs} | 6 +-- .../{IValidator.cs => INuGetValidator.cs} | 50 +++++++++---------- .../Validation/IValidationIssue.cs | 2 +- .../Entities/ValidatorStatus.cs | 8 +-- .../ValidationResult.cs | 10 ++-- 7 files changed, 41 insertions(+), 42 deletions(-) rename src/NuGet.Services.Contracts/Validation/{IProcessor.cs => INuGetProcessor.cs} (100%) rename src/NuGet.Services.Contracts/Validation/{IValidationRequest.cs => INuGetValidationRequest.cs} (85%) rename src/NuGet.Services.Contracts/Validation/{IValidationResult.cs => INuGetValidationResponse.cs} (83%) rename src/NuGet.Services.Contracts/Validation/{IValidator.cs => INuGetValidator.cs} (54%) diff --git a/src/NuGet.Services.Contracts/Validation/IProcessor.cs b/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs similarity index 100% rename from src/NuGet.Services.Contracts/Validation/IProcessor.cs rename to src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs diff --git a/src/NuGet.Services.Contracts/Validation/IValidationRequest.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs similarity index 85% rename from src/NuGet.Services.Contracts/Validation/IValidationRequest.cs rename to src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs index 49243872..e84db9e2 100644 --- a/src/NuGet.Services.Contracts/Validation/IValidationRequest.cs +++ b/src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs @@ -6,13 +6,12 @@ namespace NuGet.Services.Validation { /// - /// The details requires for requesting the status of an asynchronous validation or requesting that an - /// asynchronous validation be started. + /// The request to start or check a validation step for a NuGet package or symbol. /// - public interface IValidationRequest + public interface INuGetValidationRequest { /// - /// The identifier for a single validation execution. + /// The identifier for a single validation step execution. /// Guid ValidationId { get; } diff --git a/src/NuGet.Services.Contracts/Validation/IValidationResult.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs similarity index 83% rename from src/NuGet.Services.Contracts/Validation/IValidationResult.cs rename to src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs index a6726ca7..6cd4272f 100644 --- a/src/NuGet.Services.Contracts/Validation/IValidationResult.cs +++ b/src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs @@ -6,12 +6,12 @@ namespace NuGet.Services.Validation { /// - /// The result of an asynchronous validation. + /// The response from starting or checking a validation step for a NuGet package or symbol. /// - public interface IValidationResult + public interface INuGetValidationResponse { /// - /// The status of the validation. + /// The status of the validation step. /// ValidationStatus Status { get; } diff --git a/src/NuGet.Services.Contracts/Validation/IValidator.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidator.cs similarity index 54% rename from src/NuGet.Services.Contracts/Validation/IValidator.cs rename to src/NuGet.Services.Contracts/Validation/INuGetValidator.cs index 31474122..41286fef 100644 --- a/src/NuGet.Services.Contracts/Validation/IValidator.cs +++ b/src/NuGet.Services.Contracts/Validation/INuGetValidator.cs @@ -6,49 +6,49 @@ namespace NuGet.Services.Validation { /// - /// The interface of an asynchronous validator. This interface is how the validation orchestrator interacts + /// The interface for a NuGet package or symbol validation step. This interface is how the validation orchestrator interacts /// with the specific validation logic. A validator can either be read-only or read-write (i.e. a "processor"). If - /// the is non-null, then the validator has modified that contents - /// (.nupkg) of the package, meaning the validator is read-write. If the - /// is null, then the package content has not been modified ans the validator is read-only. Note that is it + /// the is non-null, then the validator has modified that contents + /// (.nupkg) of the package, meaning the validator is read-write. If the + /// is null, then the package content has not been modified and the validator is read-only. Note that is it /// possible for a read-write validator to return a null indicating that it chose not to /// modify the package content (e.g. no-op). If a validator is read-write, it should implement - /// and is referred to as a "processor". + /// and is referred to as a "processor". /// - public interface IValidator + public interface INuGetValidator { /// - /// A read-only method to get the result of a validation. If the - /// has not been seen by the validator before, a result with a status of - /// should be returned. The implementation can treat any combination of properties - /// as the unique identity the validation request. - /// - /// The validation request. - /// A task returning the current validation result. - Task GetResultAsync(IValidationRequest request); - - /// - /// A method that starts the validation on the provided package. If the validation has already started, this - /// method should simply return the current status as if was - /// called. If the validation has not been started yet, the implementation should start the validation and - /// return the resulting . A result with a status of + /// A method that starts the validation step on the provided package. If the validation has already started, this + /// method should simply return the current status as if was + /// called. If the validation step has not been started yet, the implementation should start the validation step and + /// return the resulting . A result with a status of /// should not be returned from this method and, if it is, the caller is free to repeat the method invocation until some /// timeout has expired, at which point the validation can be considered . /// - /// The validation request. + /// The validation step request. /// /// A task returning the current validation result indicating that the validation has been started and possibly /// already completed. /// - Task StartAsync(IValidationRequest request); + Task StartAsync(INuGetValidationRequest request); + + /// + /// A read-only method to check a validation step. If the + /// has not been seen by the validator before, a result with a status of + /// should be returned. The implementation can treat any combination of properties + /// as the unique identity the validation request. + /// + /// The validation step request. + /// The validation step's latest status. + Task GetResultAsync(INuGetValidationRequest request); /// - /// A method that can be used to clean up any state produced by . + /// A method that can be used to clean up any state produced by . /// If this method fails for some reason, an exception should be thrown. However, the caller can simply swallow /// the exception making this method a best effort. This is simply a way, in the happy path, to keep storage /// usage under control. /// - /// The validation request. - Task CleanUpAsync(IValidationRequest request); + /// The validation step request. + Task CleanUpAsync(INuGetValidationRequest request); } } diff --git a/src/NuGet.Services.Contracts/Validation/IValidationIssue.cs b/src/NuGet.Services.Contracts/Validation/IValidationIssue.cs index de663d60..4dcb359e 100644 --- a/src/NuGet.Services.Contracts/Validation/IValidationIssue.cs +++ b/src/NuGet.Services.Contracts/Validation/IValidationIssue.cs @@ -4,7 +4,7 @@ namespace NuGet.Services.Validation { /// - /// A validation issue encountered during a validation. + /// A validation issue encountered during a validation step. /// public interface IValidationIssue { diff --git a/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs b/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs index d6137119..9906559d 100644 --- a/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs +++ b/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs @@ -7,14 +7,14 @@ namespace NuGet.Services.Validation { /// - /// The status of an 's validation of a package. This should be used - /// by each to persist its state. + /// The status of an 's validation of a package. This should be used + /// by each to persist its state. /// public class ValidatorStatus { /// /// The unique identifier for this validation. The Validation Orchestrator generates a unique - /// validation ID for each it runs on a single package. + /// validation ID for each it runs on a single package. /// public Guid ValidationId { get; set; } @@ -24,7 +24,7 @@ public class ValidatorStatus public int PackageKey { get; set; } /// - /// The name of the . + /// The name of the . /// public string ValidatorName { get; set; } diff --git a/src/NuGet.Services.Validation/ValidationResult.cs b/src/NuGet.Services.Validation/ValidationResult.cs index 3bbb7e97..0b8578ea 100644 --- a/src/NuGet.Services.Validation/ValidationResult.cs +++ b/src/NuGet.Services.Validation/ValidationResult.cs @@ -6,27 +6,27 @@ namespace NuGet.Services.Validation { - public class ValidationResult : IValidationResult + public class ValidationResult : INuGetValidationResponse { /// /// Represents a validation result that has not been started. /// - public static IValidationResult NotStarted { get; } = new ValidationResult(ValidationStatus.NotStarted); + public static INuGetValidationResponse NotStarted { get; } = new ValidationResult(ValidationStatus.NotStarted); /// /// Represents a validation result that has started but not succeeded or failed yet. /// - public static IValidationResult Incomplete { get; } = new ValidationResult(ValidationStatus.Incomplete); + public static INuGetValidationResponse Incomplete { get; } = new ValidationResult(ValidationStatus.Incomplete); /// /// A successful validation result with no issues. /// - public static IValidationResult Succeeded { get; } = new ValidationResult(ValidationStatus.Succeeded); + public static INuGetValidationResponse Succeeded { get; } = new ValidationResult(ValidationStatus.Succeeded); /// /// A failed validation result with no issues. /// - public static IValidationResult Failed { get; } = new ValidationResult(ValidationStatus.Failed); + public static INuGetValidationResponse Failed { get; } = new ValidationResult(ValidationStatus.Failed); /// /// Create a new validation result with the given status. From 0458ef70baf5017b957280dc4a7a26b8095230e0 Mon Sep 17 00:00:00 2001 From: Loic Sharma Date: Tue, 26 Jan 2021 12:41:35 -0800 Subject: [PATCH 2/4] Add missing file --- src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs b/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs index 2f8dd446..86d654f3 100644 --- a/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs +++ b/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs @@ -8,7 +8,7 @@ namespace NuGet.Services.Validation /// allow the caller of the validators (e.g. orchestrator) to verify in advance that a validator (i.e. processor) /// that mutates packages does not run in parallel with any other validator. /// - public interface IProcessor : IValidator + public interface INuGetProcessor : INuGetValidator { } } From 54fd90ce7390e27fb25a70efcc3759793cbbae95 Mon Sep 17 00:00:00 2001 From: Loic Sharma Date: Tue, 26 Jan 2021 17:18:19 -0800 Subject: [PATCH 3/4] Remove validation step interfaces --- .../Validation/INuGetProcessor.cs | 14 -- .../Validation/INuGetValidationRequest.cs | 42 ------ .../Validation/INuGetValidationResponse.cs | 30 ---- .../Validation/INuGetValidator.cs | 54 -------- .../ValidationResult.cs | 130 ------------------ .../ValidationResultTests.cs | 56 -------- 6 files changed, 326 deletions(-) delete mode 100644 src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs delete mode 100644 src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs delete mode 100644 src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs delete mode 100644 src/NuGet.Services.Contracts/Validation/INuGetValidator.cs delete mode 100644 src/NuGet.Services.Validation/ValidationResult.cs delete mode 100644 tests/NuGet.Services.Validation.Tests/ValidationResultTests.cs diff --git a/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs b/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs deleted file mode 100644 index 86d654f3..00000000 --- a/src/NuGet.Services.Contracts/Validation/INuGetProcessor.cs +++ /dev/null @@ -1,14 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -namespace NuGet.Services.Validation -{ - /// - /// A marker interface to state that this validator mutates packages. The only purpose of this interface it to - /// allow the caller of the validators (e.g. orchestrator) to verify in advance that a validator (i.e. processor) - /// that mutates packages does not run in parallel with any other validator. - /// - public interface INuGetProcessor : INuGetValidator - { - } -} diff --git a/src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs deleted file mode 100644 index e84db9e2..00000000 --- a/src/NuGet.Services.Contracts/Validation/INuGetValidationRequest.cs +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -using System; - -namespace NuGet.Services.Validation -{ - /// - /// The request to start or check a validation step for a NuGet package or symbol. - /// - public interface INuGetValidationRequest - { - /// - /// The identifier for a single validation step execution. - /// - Guid ValidationId { get; } - - /// - /// The package key in the NuGet gallery database. If a package is hard deleted and created, the package key - /// will be different but the and will be the same. - /// - int PackageKey { get; } - - /// - /// The package ID. The casing of this ID need not match the author-intended casing of the ID. - /// - string PackageId { get; } - - /// - /// The package version. The casing of this version need not match the author-intended casing of the version. - /// This value is not necessarily a normalized version. - /// - string PackageVersion { get; } - - /// - /// The URL to the NuGet package content. This URL should be accessible without special authentication headers. - /// However, authentication information could be included in the URL (e.g. Azure Blob Storage SAS URL). This URL - /// need not have a single value for a specific . - /// - string NupkgUrl { get; } - } -} diff --git a/src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs deleted file mode 100644 index 6cd4272f..00000000 --- a/src/NuGet.Services.Contracts/Validation/INuGetValidationResponse.cs +++ /dev/null @@ -1,30 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -using System.Collections.Generic; - -namespace NuGet.Services.Validation -{ - /// - /// The response from starting or checking a validation step for a NuGet package or symbol. - /// - public interface INuGetValidationResponse - { - /// - /// The status of the validation step. - /// - ValidationStatus Status { get; } - - /// - /// The validation issues that were encountered. - /// - IReadOnlyList Issues { get; } - - /// - /// The URL to the modified package content (.nupkg). This URL should be accessible without special - /// authentication headers. However, authentication information could be included in the URL (e.g. Azure Blob - /// Storage SAS URL). This URL need not have a single value for a specific . - /// - string NupkgUrl { get; } - } -} \ No newline at end of file diff --git a/src/NuGet.Services.Contracts/Validation/INuGetValidator.cs b/src/NuGet.Services.Contracts/Validation/INuGetValidator.cs deleted file mode 100644 index 41286fef..00000000 --- a/src/NuGet.Services.Contracts/Validation/INuGetValidator.cs +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -using System.Threading.Tasks; - -namespace NuGet.Services.Validation -{ - /// - /// The interface for a NuGet package or symbol validation step. This interface is how the validation orchestrator interacts - /// with the specific validation logic. A validator can either be read-only or read-write (i.e. a "processor"). If - /// the is non-null, then the validator has modified that contents - /// (.nupkg) of the package, meaning the validator is read-write. If the - /// is null, then the package content has not been modified and the validator is read-only. Note that is it - /// possible for a read-write validator to return a null indicating that it chose not to - /// modify the package content (e.g. no-op). If a validator is read-write, it should implement - /// and is referred to as a "processor". - /// - public interface INuGetValidator - { - /// - /// A method that starts the validation step on the provided package. If the validation has already started, this - /// method should simply return the current status as if was - /// called. If the validation step has not been started yet, the implementation should start the validation step and - /// return the resulting . A result with a status of - /// should not be returned from this method and, if it is, the caller is free to repeat the method invocation until some - /// timeout has expired, at which point the validation can be considered . - /// - /// The validation step request. - /// - /// A task returning the current validation result indicating that the validation has been started and possibly - /// already completed. - /// - Task StartAsync(INuGetValidationRequest request); - - /// - /// A read-only method to check a validation step. If the - /// has not been seen by the validator before, a result with a status of - /// should be returned. The implementation can treat any combination of properties - /// as the unique identity the validation request. - /// - /// The validation step request. - /// The validation step's latest status. - Task GetResultAsync(INuGetValidationRequest request); - - /// - /// A method that can be used to clean up any state produced by . - /// If this method fails for some reason, an exception should be thrown. However, the caller can simply swallow - /// the exception making this method a best effort. This is simply a way, in the happy path, to keep storage - /// usage under control. - /// - /// The validation step request. - Task CleanUpAsync(INuGetValidationRequest request); - } -} diff --git a/src/NuGet.Services.Validation/ValidationResult.cs b/src/NuGet.Services.Validation/ValidationResult.cs deleted file mode 100644 index 0b8578ea..00000000 --- a/src/NuGet.Services.Validation/ValidationResult.cs +++ /dev/null @@ -1,130 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -using System; -using System.Collections.Generic; - -namespace NuGet.Services.Validation -{ - public class ValidationResult : INuGetValidationResponse - { - /// - /// Represents a validation result that has not been started. - /// - public static INuGetValidationResponse NotStarted { get; } = new ValidationResult(ValidationStatus.NotStarted); - - /// - /// Represents a validation result that has started but not succeeded or failed yet. - /// - public static INuGetValidationResponse Incomplete { get; } = new ValidationResult(ValidationStatus.Incomplete); - - /// - /// A successful validation result with no issues. - /// - public static INuGetValidationResponse Succeeded { get; } = new ValidationResult(ValidationStatus.Succeeded); - - /// - /// A failed validation result with no issues. - /// - public static INuGetValidationResponse Failed { get; } = new ValidationResult(ValidationStatus.Failed); - - /// - /// Create a new validation result with the given status. - /// - /// The result's status. - public ValidationResult(ValidationStatus status) - : this(status, issues: null, nupkgUrl: null) - { - } - - /// - /// Create a new validation result with the given status. - /// - /// The result's status. - /// - /// A URL to modified package content (.nupkg). Must be null if status is not - /// . - /// - public ValidationResult( - ValidationStatus status, - string nupkgUrl) - : this(status, issues: null, nupkgUrl: nupkgUrl) - { - } - - /// - /// Create a new validation result with the given status. - /// - /// The result's status. - /// - /// The issues that were encountered during the validation. Must be empty if status is not - /// or . - /// - public ValidationResult( - ValidationStatus status, - IReadOnlyList issues) - : this(status, issues, nupkgUrl: null) - { - } - - /// - /// Create a new failed validation result with the given errors. - /// - /// The status of the validation. - /// - /// The issues that were encountered during the validation. Must be empty if status is not - /// or . - /// - /// - /// A URL to modified package content (.nupkg). Must be null if status is not - /// . - /// - public ValidationResult( - ValidationStatus status, - IReadOnlyList issues, - string nupkgUrl) - { - if (issues?.Count > 0 && status != ValidationStatus.Succeeded && status != ValidationStatus.Failed) - { - throw new ArgumentException("Cannot specify issues if the validation is not in a terminal status.", nameof(status)); - } - - if (nupkgUrl != null && status != ValidationStatus.Succeeded) - { - throw new ArgumentException($"The {nameof(nupkgUrl)} can only be provided when the status is " + - $"{ValidationStatus.Succeeded}.", nameof(status)); - } - - Status = status; - Issues = issues ?? new IValidationIssue[0]; - NupkgUrl = nupkgUrl; - } - - /// - /// The status of the validation. - /// - public ValidationStatus Status { get; } - - /// - /// The issues that were encountered during the validation. - /// - public IReadOnlyList Issues { get; } - - /// - /// The URL to the modified NuGet package content. This URL should be accessible without special authentication - /// headers. However, authentication information could be included in the URL (e.g. Azure Blob Storage SAS URL). - /// This URL need not have a single value for a specific . - /// - public string NupkgUrl { get; } - - /// - /// Create a new failed . - /// - /// The issues for the failed validation result. - /// The failed validation result. - public static ValidationResult FailedWithIssues(params IValidationIssue[] issues) - { - return new ValidationResult(ValidationStatus.Failed, (IValidationIssue[])issues.Clone()); - } - } -} \ No newline at end of file diff --git a/tests/NuGet.Services.Validation.Tests/ValidationResultTests.cs b/tests/NuGet.Services.Validation.Tests/ValidationResultTests.cs deleted file mode 100644 index 1ab0b24c..00000000 --- a/tests/NuGet.Services.Validation.Tests/ValidationResultTests.cs +++ /dev/null @@ -1,56 +0,0 @@ -// Copyright (c) .NET Foundation. All rights reserved. -// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. - -using System; -using System.Collections.Generic; -using Xunit; - -namespace NuGet.Services.Validation.Tests -{ - public class ValidationResultTests - { - public class Constructor - { - private const string NupkgUrl = "http://example/nuget.versioning.4.5.0.nupkg"; - - [Fact] - public void DefaultsNullIssuesToEmptyList() - { - var target = new ValidationResult(ValidationStatus.Succeeded, issues: null); - - Assert.NotNull(target.Issues); - Assert.Empty(target.Issues); - } - - [Theory] - [InlineData(ValidationStatus.NotStarted)] - [InlineData(ValidationStatus.Incomplete)] - public void RejectsIssesOnNonTerminalStatus(ValidationStatus status) - { - var issues = new List { null }; - - var ex = Assert.Throws(() => new ValidationResult(status, issues)); - Assert.Equal("status", ex.ParamName); - Assert.Contains("Cannot specify issues if the validation is not in a terminal status.", ex.Message); - } - - [Theory] - [InlineData(ValidationStatus.NotStarted)] - [InlineData(ValidationStatus.Incomplete)] - [InlineData(ValidationStatus.Failed)] - public void RejectsNupkgUrlForNonSucessStatuses(ValidationStatus status) - { - var ex = Assert.Throws(() => new ValidationResult(status, NupkgUrl)); - Assert.Equal("status", ex.ParamName); - Assert.Contains("The nupkgUrl can only be provided when the status is Succeeded.", ex.Message); - } - - [Fact] - public void AllowsNupkgUrlForSuccessStatus() - { - var target = new ValidationResult(ValidationStatus.Succeeded, NupkgUrl); - Assert.Same(target.NupkgUrl, NupkgUrl); - } - } - } -} From 92729e36e7795049e3d52b4b014d5d3a6fd8c74c Mon Sep 17 00:00:00 2001 From: Loic Sharma Date: Wed, 27 Jan 2021 18:27:28 -0800 Subject: [PATCH 4/4] Update comments --- .../Validation/ValidationStatus.cs | 12 ++++++------ .../Entities/PackageValidation.cs | 2 +- .../Entities/ValidatorStatus.cs | 12 +++++++----- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/src/NuGet.Services.Contracts/Validation/ValidationStatus.cs b/src/NuGet.Services.Contracts/Validation/ValidationStatus.cs index 2a1e1467..6c856fd0 100644 --- a/src/NuGet.Services.Contracts/Validation/ValidationStatus.cs +++ b/src/NuGet.Services.Contracts/Validation/ValidationStatus.cs @@ -4,28 +4,28 @@ namespace NuGet.Services.Validation { /// - /// The status of an asynchronous validation. + /// The status of a single validation step. /// public enum ValidationStatus { /// - /// The validation has not started yet. + /// The validation step has not started yet. /// NotStarted = 0, /// - /// The validation is incomplete and should therefore be in progress. + /// The validation step is incomplete and should therefore be in progress. /// Incomplete = 1, /// - /// The validation has succeeded and no validation errors have occurred. Any transient errors that may have - /// occurred during the validation have been resolved. + /// The validation step has succeeded and no validation errors have occurred. Any transient errors that may have + /// occurred during the validation step have been resolved. /// Succeeded = 2, /// - /// The validation has failed. This could be a failure in initiating the validation, the validation has timed + /// The validation step has failed. This could be a failure in initiating the validation, the validation has timed /// out, or the logic of the validation has discovered an issue with the entity that is being validated. /// Failed = 3, diff --git a/src/NuGet.Services.Validation/Entities/PackageValidation.cs b/src/NuGet.Services.Validation/Entities/PackageValidation.cs index ae386831..0012e132 100644 --- a/src/NuGet.Services.Validation/Entities/PackageValidation.cs +++ b/src/NuGet.Services.Validation/Entities/PackageValidation.cs @@ -7,7 +7,7 @@ namespace NuGet.Services.Validation { /// - /// Represents a single validation performed on a package. The associated package is implied via the validations's + /// Represents a single validation step performed on a package. The associated package is implied via the validations's /// . /// public class PackageValidation diff --git a/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs b/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs index 9906559d..8f93077c 100644 --- a/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs +++ b/src/NuGet.Services.Validation/Entities/ValidatorStatus.cs @@ -7,14 +7,16 @@ namespace NuGet.Services.Validation { /// - /// The status of an 's validation of a package. This should be used - /// by each to persist its state. + /// The Orchestrator integrates with a downstream validation job by implementing a "validator". + /// The Orchestrator, through its validator, creates this entity when it starts a new validation step + /// and polls the entity to receive status updates. Meanwhile, the downstream validation job + /// passes information back to the Orchestrator by updating this entity. /// public class ValidatorStatus { /// - /// The unique identifier for this validation. The Validation Orchestrator generates a unique - /// validation ID for each it runs on a single package. + /// The unique identifier for this validation step. The Validation Orchestrator generates a unique + /// validation ID for each validation step it runs on a single package. /// public Guid ValidationId { get; set; } @@ -24,7 +26,7 @@ public class ValidatorStatus public int PackageKey { get; set; } /// - /// The name of the . + /// The name of the "validator" for this validation step. /// public string ValidatorName { get; set; }