diff --git a/src/NuGet.Services.Contracts/Validation/IProcessor.cs b/src/NuGet.Services.Contracts/Validation/IProcessor.cs deleted file mode 100644 index 2f8dd446..00000000 --- a/src/NuGet.Services.Contracts/Validation/IProcessor.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 IProcessor : IValidator - { - } -} 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.Contracts/Validation/IValidationRequest.cs b/src/NuGet.Services.Contracts/Validation/IValidationRequest.cs deleted file mode 100644 index 49243872..00000000 --- a/src/NuGet.Services.Contracts/Validation/IValidationRequest.cs +++ /dev/null @@ -1,43 +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 details requires for requesting the status of an asynchronous validation or requesting that an - /// asynchronous validation be started. - /// - public interface IValidationRequest - { - /// - /// The identifier for a single validation 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/IValidationResult.cs b/src/NuGet.Services.Contracts/Validation/IValidationResult.cs deleted file mode 100644 index a6726ca7..00000000 --- a/src/NuGet.Services.Contracts/Validation/IValidationResult.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 result of an asynchronous validation. - /// - public interface IValidationResult - { - /// - /// The status of the validation. - /// - 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/IValidator.cs b/src/NuGet.Services.Contracts/Validation/IValidator.cs deleted file mode 100644 index 31474122..00000000 --- a/src/NuGet.Services.Contracts/Validation/IValidator.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 of an asynchronous validator. 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 - /// 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 IValidator - { - /// - /// 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 - /// 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. - /// - /// A task returning the current validation result indicating that the validation has been started and possibly - /// already completed. - /// - Task StartAsync(IValidationRequest 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 request. - Task CleanUpAsync(IValidationRequest request); - } -} 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 d6137119..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; } diff --git a/src/NuGet.Services.Validation/ValidationResult.cs b/src/NuGet.Services.Validation/ValidationResult.cs deleted file mode 100644 index 3bbb7e97..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 : IValidationResult - { - /// - /// Represents a validation result that has not been started. - /// - public static IValidationResult 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); - - /// - /// A successful validation result with no issues. - /// - public static IValidationResult Succeeded { get; } = new ValidationResult(ValidationStatus.Succeeded); - - /// - /// A failed validation result with no issues. - /// - public static IValidationResult 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); - } - } - } -}