Introduce package deprecation entities and migration (#6820)

Author: Scott Bommarito

src/NuGet.Services.Entities/NuGet.Services.Entities.csproj

@@ -67,6 +67,8 @@
     <Compile Include="PackageAuthor.cs" />
     <Compile Include="PackageDelete.cs" />
     <Compile Include="PackageDependency.cs" />
+    <Compile Include="PackageDeprecation.cs" />
+    <Compile Include="PackageDeprecationStatus.cs" />
     <Compile Include="PackageEditReadMeState.cs" />
     <Compile Include="PackageFramework.cs" />
     <Compile Include="PackageHistory.cs" />

src/NuGet.Services.Entities/Package.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.ComponentModel.DataAnnotations;
 using System.ComponentModel.DataAnnotations.Schema;
+using System.Linq;
 
 namespace NuGet.Services.Entities
 {
@@ -22,6 +23,8 @@ public Package()
             PackageTypes = new HashSet<PackageType>();
             SupportedFrameworks = new HashSet<PackageFramework>();
             SymbolPackages = new HashSet<SymbolPackage>();
+            Deprecations = new HashSet<PackageDeprecation>();
+            AlternativeOf = new HashSet<PackageDeprecation>();
             Listed = true;
         }
 #pragma warning restore 618
@@ -251,5 +254,22 @@ public bool HasReadMe
 
         [StringLength(500)]
         public string LicenseExpression { get; set; }
+
+        /// <summary>
+        /// Gets and sets the deprecations associated with this package.
+        /// </summary>
+        /// <remarks>
+        /// In the future, a package may have multiple deprecations associated with it, one visible and others hidden.
+        /// The visible deprecation will be the deprecation shown in the UI to users.
+        /// The hidden deprecations will consist of information about the package that we recommend package owners apply to their package.
+        /// For now, we only support a single deprecation per package (the visible deprecation).
+        /// </remarks>
+        public virtual ICollection<PackageDeprecation> Deprecations { get; set; }
+
+        /// <summary>
+        /// Gets and sets the list of deprecations that recommend this package as an alternative.
+        /// See <see cref="PackageDeprecation.AlternatePackage"/>.
+        /// </summary>
+        public virtual ICollection<PackageDeprecation> AlternativeOf { get; set; }
     }
 }

src/NuGet.Services.Entities/PackageDeprecation.cs

@@ -0,0 +1,107 @@
+// 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.ComponentModel.DataAnnotations;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace NuGet.Services.Entities
+{
+    /// <summary>
+    /// Represents a package deprecation.
+    /// </summary>
+    public class PackageDeprecation
+        : IEntity
+    {
+        /// <summary>
+        /// Gets or sets the primary key for the entity.
+        /// </summary>
+        public int Key { get; set; }
+        
+        /// <summary>
+        /// Gets or sets the package affected by this deprecation.
+        /// </summary>
+        public virtual Package Package { get; set; }
+
+        /// <summary>
+        /// Gets or sets the key of the package affected by this deprecation.
+        /// </summary>
+        [Index(IsUnique = true)]
+        public int PackageKey { get; set; }
+
+        /// <summary>
+        /// Gets or sets the status of this deprecation.
+        /// </summary>
+        /// <remarks>
+        /// A <see cref="PackageDeprecation"/> with a <see cref="PackageDeprecationStatus"/> of <see cref="PackageDeprecationStatus.NotDeprecated"/> is meaningless, so <see cref="Status"/> must be at least <c>1</c>.
+        /// </remarks>
+        [Range(1, int.MaxValue)]
+        public PackageDeprecationStatus Status { get; set; }
+
+        /// <summary>
+        /// Gets or sets the alternate package registration entity.
+        /// It is recommended that users use this package registration instead of the deprecated package.
+        /// </summary>
+        public virtual PackageRegistration AlternatePackageRegistration { get; set; }
+
+        /// <summary>
+        /// Gets or sets the alternate package registration entity key.
+        /// It is recommended that users use this package registration instead of the deprecated package.
+        /// </summary>
+        public int? AlternatePackageRegistrationKey { get; set; }
+
+        /// <summary>
+        /// Gets or sets the alternate package entity.
+        /// It is recommended that users use this package instead of the deprecated package.
+        /// </summary>
+        public virtual Package AlternatePackage { get; set; }
+
+        /// <summary>
+        /// Gets or sets the alternate package entity key.
+        /// It is recommended that users use this package instead of the deprecated package.
+        /// </summary>
+        public int? AlternatePackageKey { get; set; }
+
+        /// <summary>
+        /// Gets or sets the user that executed the package deprecation.
+        /// </summary>
+        public virtual User DeprecatedByUser { get; set; }
+
+        /// <summary>
+        /// Gets or sets the key of the user that executed the package deprecation.
+        /// </summary>
+        public int? DeprecatedByUserKey { get; set; }
+
+        /// <summary>
+        /// The date when the package was deprecated.
+        /// </summary>
+        [DatabaseGenerated(DatabaseGeneratedOption.Computed)]
+        public DateTime DeprecatedOn { get; set; }
+
+        /// <summary>
+        /// Gets or sets the user-provided custom message for this package deprecation.
+        /// </summary>
+        public string CustomMessage { get; set; }
+
+        /// <summary>
+        /// Gets or sets the CVSS rating for this deprecation.
+        /// </summary>
+        /// <remarks>
+        /// CVSS ratings are from 0.0 to 10.0 and have a single point of precision.
+        /// </remarks>
+        [Range(0, 10)]
+        public decimal? CVSSRating { get; set; }
+
+        /// <summary>
+        /// Gets or sets the serialized JSON object containing an array of CVE ID's related to this deprecation.
+        /// The JSON object should have a version property that defines the version of its schema.
+        /// </summary>
+        public string CVEIds { get; set; }
+
+        /// <summary>
+        /// Gets or sets the serialized JSON object containing an array of CWE ID's related to this deprecation.
+        /// The JSON object should have a version property that defines the version of its schema.
+        /// </summary>
+        public string CWEIds { get; set; }
+    }
+}

src/NuGet.Services.Entities/PackageDeprecationStatus.cs

@@ -0,0 +1,34 @@
+// 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.Entities
+{
+    /// <summary>
+    /// Indicates package deprecation status and reason(s).
+    /// </summary>
+    [Flags]
+    public enum PackageDeprecationStatus
+    {
+        /// <summary>
+        /// The package is not deprecated.
+        /// </summary>
+        NotDeprecated = 0,
+
+        /// <summary>
+        /// The package is deprecated because of some other undefined reason.
+        /// </summary>
+        Other = 1,
+
+        /// <summary>
+        /// The package is deprecated because it is legacy and no longer maintained.
+        /// </summary>
+        Legacy = 2,
+
+        /// <summary>
+        /// The package is deprecated because it is vulnerable.
+        /// </summary>
+        Vulnerable = 4
+    }
+}

src/NuGet.Services.Entities/PackageRegistration.cs

@@ -15,6 +15,7 @@ public PackageRegistration()
             Packages = new HashSet<Package>();
             ReservedNamespaces = new HashSet<ReservedNamespace>();
             RequiredSigners = new HashSet<User>();
+            AlternativeOf = new HashSet<PackageDeprecation>();
         }
 
         [StringLength(Constants.MaxPackageIdLength)]
@@ -37,5 +38,11 @@ public PackageRegistration()
         public virtual ICollection<User> RequiredSigners { get; set; }
 
         public int Key { get; set; }
+
+        /// <summary>
+        /// Gets and sets the list of deprecations that recommend this package registration as an alternative.
+        /// See <see cref="PackageDeprecation.AlternatePackageRegistration"/>.
+        /// </summary>
+        public virtual ICollection<PackageDeprecation> AlternativeOf { get; set; }
     }
 }

src/NuGetGallery.Core/Entities/EntitiesContext.cs

@@ -367,6 +367,37 @@ protected override void OnModelCreating(DbModelBuilder modelBuilder)
             modelBuilder.Entity<SymbolPackage>()
                 .Property(s => s.RowVersion)
                 .IsRowVersion();
+
+            modelBuilder.Entity<PackageDeprecation>()
+                .HasKey(d => d.Key);
+
+            modelBuilder.Entity<Package>()
+                .HasMany(p => p.Deprecations)
+                .WithRequired(d => d.Package)
+                .HasForeignKey(d => d.PackageKey)
+                .WillCascadeOnDelete(true);
+
+            modelBuilder.Entity<Package>()
+                .HasMany(p => p.AlternativeOf)
+                .WithOptional(d => d.AlternatePackage)
+                .HasForeignKey(d => d.AlternatePackageKey)
+                .WillCascadeOnDelete(false);
+
+            modelBuilder.Entity<PackageRegistration>()
+                .HasMany(p => p.AlternativeOf)
+                .WithOptional(d => d.AlternatePackageRegistration)
+                .HasForeignKey(d => d.AlternatePackageRegistrationKey)
+                .WillCascadeOnDelete(false);
+
+            modelBuilder.Entity<PackageDeprecation>()
+                .HasOptional(d => d.DeprecatedByUser)
+                .WithMany()
+                .HasForeignKey(d => d.DeprecatedByUserKey)
+                .WillCascadeOnDelete(false);
+
+            modelBuilder.Entity<PackageDeprecation>()
+                .Property(v => v.CVSSRating)
+                .HasPrecision(3, 1);
         }
 #pragma warning restore 618
     }

src/NuGetGallery/Migrations/201901142143060_AddDeprecationEntities.Designer.cs

@@ -0,0 +1,53 @@
+namespace NuGetGallery.Migrations
+{
+    using System;
+    using System.Data.Entity.Migrations;
+    
+    public partial class AddDeprecationEntities : DbMigration
+    {
+        public override void Up()
+        {
+            CreateTable(
+                "dbo.PackageDeprecations",
+                c => new
+                    {
+                        Key = c.Int(nullable: false, identity: true),
+                        PackageKey = c.Int(nullable: false),
+                        Status = c.Int(nullable: false),
+                        AlternatePackageRegistrationKey = c.Int(),
+                        AlternatePackageKey = c.Int(),
+                        DeprecatedByUserKey = c.Int(),
+                        DeprecatedOn = c.DateTime(nullable: false, defaultValueSql: "GETUTCDATE()"),
+                        CustomMessage = c.String(),
+                        CVSSRating = c.Decimal(precision: 3, scale: 1),
+                        CVEIds = c.String(),
+                        CWEIds = c.String(),
+                    })
+                .PrimaryKey(t => t.Key)
+                .ForeignKey("dbo.Packages", t => t.AlternatePackageKey)
+                .ForeignKey("dbo.Packages", t => t.PackageKey, cascadeDelete: true)
+                .ForeignKey("dbo.Users", t => t.DeprecatedByUserKey)
+                .ForeignKey("dbo.PackageRegistrations", t => t.AlternatePackageRegistrationKey)
+                .Index(t => t.PackageKey, unique: true)
+                .Index(t => t.AlternatePackageRegistrationKey)
+                .Index(t => t.AlternatePackageKey)
+                .Index(t => t.DeprecatedByUserKey);
+            
+            Sql("ALTER TABLE [dbo].[PackageDeprecations] ADD CONSTRAINT [dbo.PackageDeprecations_CVSSRating] CHECK ([CVSSRating] >= 0 AND [CVSSRating] <= 10)");
+
+        }
+        
+        public override void Down()
+        {
+            DropForeignKey("dbo.PackageDeprecations", "AlternatePackageRegistrationKey", "dbo.PackageRegistrations");
+            DropForeignKey("dbo.PackageDeprecations", "DeprecatedByUserKey", "dbo.Users");
+            DropForeignKey("dbo.PackageDeprecations", "PackageKey", "dbo.Packages");
+            DropForeignKey("dbo.PackageDeprecations", "AlternatePackageKey", "dbo.Packages");
+            DropIndex("dbo.PackageDeprecations", new[] { "DeprecatedByUserKey" });
+            DropIndex("dbo.PackageDeprecations", new[] { "AlternatePackageKey" });
+            DropIndex("dbo.PackageDeprecations", new[] { "AlternatePackageRegistrationKey" });
+            DropIndex("dbo.PackageDeprecations", new[] { "PackageKey" });
+            DropTable("dbo.PackageDeprecations");
+        }
+    }
+}