reimplement assembly caching (#187)

This commit ensures DLLs are copied to the cache directory only if they changed, to avoid breaking debugging support unless necessary. To support this change, the assembly hash file has been replaced with a more detailed JSON structure, which is used to determine whether the cache is up-to-date and whether to use the cached or original assembly. Some mods contain multiple DLLs, which must be kept together to prevent assembly resolution issues; to simplify that (and avoid orphaned cache entries), each mod now has its own separate cache.

7 files changed, 193 insertions, 74 deletions

diff --git a/src/StardewModdingAPI/Framework/AssemblyRewriting/AssemblyTypeRewriter.cs b/src/StardewModdingAPI/Framework/AssemblyRewriting/AssemblyTypeRewriter.cs
index 3459488e..9d4d6b11 100644
--- a/src/StardewModdingAPI/Framework/AssemblyRewriting/AssemblyTypeRewriter.cs
+++ b/src/StardewModdingAPI/Framework/AssemblyRewriting/AssemblyTypeRewriter.cs
@@ -54,7 +54,8 @@ namespace StardewModdingAPI.Framework.AssemblyRewriting
 
         /// <summary>Rewrite the types referenced by an assembly.</summary>
         /// <param name="assembly">The assembly to rewrite.</param>
-        public void RewriteAssembly(AssemblyDefinition assembly)
+        /// <returns>Returns whether the assembly was modified.</returns>
+        public bool RewriteAssembly(AssemblyDefinition assembly)
         {
             ModuleDefinition module = assembly.Modules.Single(); // technically an assembly can have multiple modules, but none of the build tools (including MSBuild) support it; simplify by assuming one module
 
@@ -71,7 +72,7 @@ namespace StardewModdingAPI.Framework.AssemblyRewriting
                 }
             }
             if (!shouldRewrite)
-                return;
+                return false;
 
             // add target assembly references
             foreach (AssemblyNameReference target in this.AssemblyMap.TargetReferences.Values)
@@ -117,6 +118,7 @@ namespace StardewModdingAPI.Framework.AssemblyRewriting
                 }
                 method.Body.OptimizeMacros();
             }
+            return true;
         }
 
 
diff --git a/src/StardewModdingAPI/Framework/AssemblyRewriting/CacheEntry.cs b/src/StardewModdingAPI/Framework/AssemblyRewriting/CacheEntry.cs
new file mode 100644
index 00000000..3dfbc78c
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/AssemblyRewriting/CacheEntry.cs
@@ -0,0 +1,46 @@
+using System.IO;
+
+namespace StardewModdingAPI.Framework.AssemblyRewriting
+{
+    /// <summary>Represents cached metadata for a rewritten assembly.</summary>
+    internal class CacheEntry
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The MD5 hash for the original assembly.</summary>
+        public readonly string Hash;
+
+        /// <summary>The SMAPI version used to rewrite the assembly.</summary>
+        public readonly string ApiVersion;
+
+        /// <summary>Whether to use the cached assembly instead of the original assembly.</summary>
+        public readonly bool UseCachedAssembly;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="hash">The MD5 hash for the original assembly.</param>
+        /// <param name="apiVersion">The SMAPI version used to rewrite the assembly.</param>
+        /// <param name="useCachedAssembly">Whether to use the cached assembly instead of the original assembly.</param>
+        public CacheEntry(string hash, string apiVersion, bool useCachedAssembly)
+        {
+            this.Hash = hash;
+            this.ApiVersion = apiVersion;
+            this.UseCachedAssembly = useCachedAssembly;
+        }
+
+        /// <summary>Get whether the cache entry is up-to-date for the given assembly hash.</summary>
+        /// <param name="paths">The paths for the cached assembly.</param>
+        /// <param name="hash">The MD5 hash of the original assembly.</param>
+        /// <param name="currentVersion">The current SMAPI version.</param>
+        public bool IsUpToDate(CachePaths paths, string hash, Version currentVersion)
+        {
+            return hash == this.Hash
+                && this.ApiVersion == currentVersion.ToString()
+                && (!this.UseCachedAssembly || File.Exists(paths.Assembly));
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Framework/AssemblyRewriting/CachePaths.cs b/src/StardewModdingAPI/Framework/AssemblyRewriting/CachePaths.cs
index 17c4d188..18861873 100644
--- a/src/StardewModdingAPI/Framework/AssemblyRewriting/CachePaths.cs
+++ b/src/StardewModdingAPI/Framework/AssemblyRewriting/CachePaths.cs
@@ -12,8 +12,8 @@ namespace StardewModdingAPI.Framework.AssemblyRewriting
         /// <summary>The file path of the assembly file.</summary>
         public string Assembly { get; }
 
-        /// <summary>The file path containing the MD5 hash for the assembly.</summary>
-        public string Hash { get; }
+        /// <summary>The file path containing the assembly metadata.</summary>
+        public string Metadata { get; }
 
 
         /*********
@@ -22,12 +22,12 @@ namespace StardewModdingAPI.Framework.AssemblyRewriting
         /// <summary>Construct an instance.</summary>
         /// <param name="directory">The directory path which contains the assembly.</param>
         /// <param name="assembly">The file path of the assembly file.</param>
-        /// <param name="hash">The file path containing the MD5 hash for the assembly.</param>
-        public CachePaths(string directory, string assembly, string hash)
+        /// <param name="metadata">The file path containing the assembly metadata.</param>
+        public CachePaths(string directory, string assembly, string metadata)
         {
             this.Directory = directory;
             this.Assembly = assembly;
-            this.Hash = hash;
+            this.Metadata = metadata;
         }
     }
 }
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Framework/AssemblyRewriting/RewriteResult.cs b/src/StardewModdingAPI/Framework/AssemblyRewriting/RewriteResult.cs
new file mode 100644
index 00000000..8f34bb20
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/AssemblyRewriting/RewriteResult.cs
@@ -0,0 +1,49 @@
+namespace StardewModdingAPI.Framework.AssemblyRewriting
+{
+    /// <summary>Metadata about a preprocessed assembly.</summary>
+    internal class RewriteResult
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The original assembly path.</summary>
+        public readonly string OriginalAssemblyPath;
+
+        /// <summary>The cache paths.</summary>
+        public readonly CachePaths CachePaths;
+
+        /// <summary>The rewritten assembly bytes.</summary>
+        public readonly byte[] AssemblyBytes;
+
+        /// <summary>The MD5 hash for the original assembly.</summary>
+        public readonly string Hash;
+
+        /// <summary>Whether to use the cached assembly instead of the original assembly.</summary>
+        public readonly bool UseCachedAssembly;
+
+        /// <summary>Whether this data is newer than the cache.</summary>
+        public readonly bool IsNewerThanCache;
+
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="originalAssemblyPath"></param>
+        /// <param name="cachePaths">The cache paths.</param>
+        /// <param name="assemblyBytes">The rewritten assembly bytes.</param>
+        /// <param name="hash">The MD5 hash for the original assembly.</param>
+        /// <param name="useCachedAssembly">Whether to use the cached assembly instead of the original assembly.</param>
+        /// <param name="isNewerThanCache">Whether this data is newer than the cache.</param>
+        public RewriteResult(string originalAssemblyPath, CachePaths cachePaths, byte[] assemblyBytes, string hash, bool useCachedAssembly, bool isNewerThanCache)
+        {
+            this.OriginalAssemblyPath = originalAssemblyPath;
+            this.CachePaths = cachePaths;
+            this.Hash = hash;
+            this.AssemblyBytes = assemblyBytes;
+            this.UseCachedAssembly = useCachedAssembly;
+            this.IsNewerThanCache = isNewerThanCache;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/ModAssemblyLoader.cs b/src/StardewModdingAPI/Framework/ModAssemblyLoader.cs
index 51018b0b..1ceb8ad2 100644
--- a/src/StardewModdingAPI/Framework/ModAssemblyLoader.cs
+++ b/src/StardewModdingAPI/Framework/ModAssemblyLoader.cs
@@ -1,9 +1,11 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Reflection;
 using System.Security.Cryptography;
 using Mono.Cecil;
+using Newtonsoft.Json;
 using StardewModdingAPI.AssemblyRewriters;
 using StardewModdingAPI.Framework.AssemblyRewriting;
 
@@ -15,8 +17,8 @@ namespace StardewModdingAPI.Framework
         /*********
         ** Properties
         *********/
-        /// <summary>The directory in which to cache data.</summary>
-        private readonly string CacheDirPath;
+        /// <summary>The name of the directory containing a mod's cached data.</summary>
+        private readonly string CacheDirName;
 
         /// <summary>Metadata for mapping assemblies to the current <see cref="Platform"/>.</summary>
         private readonly PlatformAssemblyMap AssemblyMap;
@@ -32,74 +34,76 @@ namespace StardewModdingAPI.Framework
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
-        /// <param name="cacheDirPath">The cache directory.</param>
+        /// <param name="cacheDirName">The name of the directory containing a mod's cached data.</param>
         /// <param name="targetPlatform">The current game platform.</param>
         /// <param name="monitor">Encapsulates monitoring and logging.</param>
-        public ModAssemblyLoader(string cacheDirPath, Platform targetPlatform, IMonitor monitor)
+        public ModAssemblyLoader(string cacheDirName, Platform targetPlatform, IMonitor monitor)
         {
-            this.CacheDirPath = cacheDirPath;
+            this.CacheDirName = cacheDirName;
             this.Monitor = monitor;
             this.AssemblyMap = Constants.GetAssemblyMap(targetPlatform);
             this.AssemblyTypeRewriter = new AssemblyTypeRewriter(this.AssemblyMap, monitor);
         }
 
-        /// <summary>Preprocess an assembly and cache the modified version.</summary>
+        /// <summary>Preprocess an assembly unless the cache is up to date.</summary>
         /// <param name="assemblyPath">The assembly file path.</param>
-        public void ProcessAssembly(string assemblyPath)
+        /// <returns>Returns the rewrite metadata for the preprocessed assembly.</returns>
+        public RewriteResult ProcessAssemblyUnlessCached(string assemblyPath)
         {
             // read assembly data
-            string assemblyFileName = Path.GetFileName(assemblyPath);
-            string assemblyDir = Path.GetDirectoryName(assemblyPath);
             byte[] assemblyBytes = File.ReadAllBytes(assemblyPath);
-            string hash = $"SMAPI {Constants.Version}|" + string.Join("", MD5.Create().ComputeHash(assemblyBytes).Select(p => p.ToString("X2")));
+            string hash = string.Join("", MD5.Create().ComputeHash(assemblyBytes).Select(p => p.ToString("X2")));
 
-            // check cache
-            CachePaths cachePaths = this.GetCacheInfo(assemblyPath);
-            bool canUseCache = File.Exists(cachePaths.Assembly) && File.Exists(cachePaths.Hash) && hash == File.ReadAllText(cachePaths.Hash);
-
-            // process assembly if not cached
-            if (!canUseCache)
+            // get cached result if current
+            CachePaths cachePaths = this.GetCachePaths(assemblyPath);
+            {
+                CacheEntry cacheEntry = File.Exists(cachePaths.Metadata) ? JsonConvert.DeserializeObject<CacheEntry>(File.ReadAllText(cachePaths.Metadata)) : null;
+                if (cacheEntry != null && cacheEntry.IsUpToDate(cachePaths, hash, Constants.Version))
+                    return new RewriteResult(assemblyPath, cachePaths, assemblyBytes, cacheEntry.Hash, cacheEntry.UseCachedAssembly, isNewerThanCache: false); // no rewrite needed
+            }
+            this.Monitor.Log($"Preprocessing {Path.GetFileName(assemblyPath)} for compatibility...", LogLevel.Trace);
+
+            // rewrite assembly
+            AssemblyDefinition assembly;
+            using (Stream readStream = new MemoryStream(assemblyBytes))
+                assembly = AssemblyDefinition.ReadAssembly(readStream);
+            bool modified = this.AssemblyTypeRewriter.RewriteAssembly(assembly);
+            using (MemoryStream outStream = new MemoryStream())
             {
-                this.Monitor.Log($"Loading {assemblyFileName} for the first time; preprocessing...", LogLevel.Trace);
-
-                // read assembly definition
-                AssemblyDefinition assembly;
-                using (Stream readStream = new MemoryStream(assemblyBytes))
-                    assembly = AssemblyDefinition.ReadAssembly(readStream);
-
-                // rewrite assembly to match platform
-                this.AssemblyTypeRewriter.RewriteAssembly(assembly);
-
-                // write cache
-                using (MemoryStream outStream = new MemoryStream())
-                {
-                    // get assembly bytes
-                    assembly.Write(outStream);
-                    byte[] outBytes = outStream.ToArray();
-
-                    // write assembly data
-                    Directory.CreateDirectory(cachePaths.Directory);
-                    File.WriteAllBytes(cachePaths.Assembly, outBytes);
-                    File.WriteAllText(cachePaths.Hash, hash);
-
-                    // copy any mdb/pdb files
-                    foreach (string path in Directory.GetFiles(assemblyDir, "*.mdb").Concat(Directory.GetFiles(assemblyDir, "*.pdb")))
-                    {
-                        string filename = Path.GetFileName(path);
-                        File.Copy(path, Path.Combine(cachePaths.Directory, filename), overwrite: true);
-                    }
-                }
+                assembly.Write(outStream);
+                byte[] outBytes = outStream.ToArray();
+                return new RewriteResult(assemblyPath, cachePaths, outBytes, hash, useCachedAssembly: modified, isNewerThanCache: true);
             }
         }
 
-        /// <summary>Load a preprocessed assembly.</summary>
-        /// <param name="assemblyPath">The assembly file path.</param>
-        public Assembly LoadCachedAssembly(string assemblyPath)
+        /// <summary>Write rewritten assembly metadata to the cache for a mod.</summary>
+        /// <param name="results">The rewrite results.</param>
+        /// <param name="forceCacheAssemblies">Whether to write all assemblies to the cache, even if they weren't modified.</param>
+        /// <exception cref="InvalidOperationException">There are no results to write, or the results are not all for the same directory.</exception>
+        public void WriteCache(IEnumerable<RewriteResult> results, bool forceCacheAssemblies)
         {
-            CachePaths cachePaths = this.GetCacheInfo(assemblyPath);
-            if (!File.Exists(cachePaths.Assembly))
-                throw new InvalidOperationException($"The assembly {assemblyPath} doesn't exist in the preprocessed cache.");
-            return Assembly.UnsafeLoadFrom(cachePaths.Assembly); // unsafe load allows DLLs downloaded from the Internet without the user needing to 'unblock' them
+            results = results.ToArray();
+
+            // get cache directory
+            if (!results.Any())
+                throw new InvalidOperationException("There are no assemblies to cache.");
+            if (results.Select(p => p.CachePaths.Directory).Distinct().Count() > 1)
+                throw new InvalidOperationException("The assemblies can't be cached together because they have different source directories.");
+            string cacheDir = results.Select(p => p.CachePaths.Directory).First();
+
+            // reset cache
+            if (Directory.Exists(cacheDir))
+                Directory.Delete(cacheDir, recursive: true);
+            Directory.CreateDirectory(cacheDir);
+
+            // cache all results
+            foreach (RewriteResult result in results)
+            {
+                CacheEntry cacheEntry = new CacheEntry(result.Hash, Constants.Version.ToString(), forceCacheAssemblies || result.UseCachedAssembly);
+                File.WriteAllText(result.CachePaths.Metadata, JsonConvert.SerializeObject(cacheEntry));
+                if (forceCacheAssemblies || result.UseCachedAssembly)
+                    File.WriteAllBytes(result.CachePaths.Assembly, result.AssemblyBytes);
+            }
         }
 
         /// <summary>Resolve an assembly from its name.</summary>
@@ -124,13 +128,13 @@ namespace StardewModdingAPI.Framework
         *********/
         /// <summary>Get the cache details for an assembly.</summary>
         /// <param name="assemblyPath">The assembly file path.</param>
-        private CachePaths GetCacheInfo(string assemblyPath)
+        private CachePaths GetCachePaths(string assemblyPath)
         {
-            string key = Path.GetFileNameWithoutExtension(assemblyPath);
-            string dirPath = Path.Combine(this.CacheDirPath, new DirectoryInfo(Path.GetDirectoryName(assemblyPath)).Name);
-            string cacheAssemblyPath = Path.Combine(dirPath, $"{key}.dll");
-            string cacheHashPath = Path.Combine(dirPath, $"{key}.hash");
-            return new CachePaths(dirPath, cacheAssemblyPath, cacheHashPath);
+            string fileName = Path.GetFileName(assemblyPath);
+            string dirPath = Path.Combine(Path.GetDirectoryName(assemblyPath), this.CacheDirName);
+            string cacheAssemblyPath = Path.Combine(dirPath, fileName);
+            string metadataPath = Path.Combine(dirPath, $"{fileName}.json");
+            return new CachePaths(dirPath, cacheAssemblyPath, metadataPath);
         }
     }
 }
diff --git a/src/StardewModdingAPI/Program.cs b/src/StardewModdingAPI/Program.cs
index e648ed64..a46f7a3e 100644
--- a/src/StardewModdingAPI/Program.cs
+++ b/src/StardewModdingAPI/Program.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Globalization;
 using System.IO;
 using System.Linq;
@@ -12,6 +13,7 @@ using Newtonsoft.Json;
 using StardewModdingAPI.AssemblyRewriters;
 using StardewModdingAPI.Events;
 using StardewModdingAPI.Framework;
+using StardewModdingAPI.Framework.AssemblyRewriting;
 using StardewModdingAPI.Inheritance;
 using StardewValley;
 using Monitor = StardewModdingAPI.Framework.Monitor;
@@ -38,8 +40,8 @@ namespace StardewModdingAPI
         /// <summary>The full path to the folder containing mods.</summary>
         private static readonly string ModPath = Path.Combine(Constants.ExecutionPath, "Mods");
 
-        /// <summary>The full path to the folder containing cached SMAPI data.</summary>
-        private static readonly string CachePath = Path.Combine(Program.ModPath, ".cache");
+        /// <summary>The name of the folder containing a mod's cached assembly data.</summary>
+        private static readonly string CacheDirName = ".cache";
 
         /// <summary>The log file to which to write messages.</summary>
         private static readonly LogFileManager LogFile = new LogFileManager(Constants.LogPath);
@@ -134,7 +136,6 @@ namespace StardewModdingAPI
                 Program.Monitor.Log("Loading SMAPI...");
                 Console.Title = Constants.ConsoleTitle;
                 Program.VerifyPath(Program.ModPath);
-                Program.VerifyPath(Program.CachePath);
                 Program.VerifyPath(Constants.LogDir);
                 if (!File.Exists(Program.GameExecutablePath))
                 {
@@ -304,7 +305,7 @@ namespace StardewModdingAPI
             Program.Monitor.Log("Loading mods...");
 
             // get assembly loader
-            ModAssemblyLoader modAssemblyLoader = new ModAssemblyLoader(Program.CachePath, Program.TargetPlatform, Program.Monitor);
+            ModAssemblyLoader modAssemblyLoader = new ModAssemblyLoader(Program.CacheDirName, Program.TargetPlatform, Program.Monitor);
             AppDomain.CurrentDomain.AssemblyResolve += (sender, e) => modAssemblyLoader.ResolveAssembly(e.Name);
 
             // load mods
@@ -401,14 +402,15 @@ namespace StardewModdingAPI
                     }
                 }
 
-                // preprocess mod assemblies
+                // preprocess mod assemblies for compatibility
+                var processedAssemblies = new List<RewriteResult>();
                 {
                     bool succeeded = true;
                     foreach (string assemblyPath in Directory.GetFiles(directory, "*.dll"))
                     {
                         try
                         {
-                            modAssemblyLoader.ProcessAssembly(assemblyPath);
+                            processedAssemblies.Add(modAssemblyLoader.ProcessAssemblyUnlessCached(assemblyPath));
                         }
                         catch (Exception ex)
                         {
@@ -420,13 +422,27 @@ namespace StardewModdingAPI
                     if (!succeeded)
                         continue;
                 }
+                bool forceUseCachedAssembly = processedAssemblies.Any(p => p.UseCachedAssembly); // make sure DLLs are kept together for dependency resolution
+                if (processedAssemblies.Any(p => p.IsNewerThanCache))
+                    modAssemblyLoader.WriteCache(processedAssemblies, forceUseCachedAssembly);
 
-                // load assembly
+                // get entry assembly path
+                string mainAssemblyPath;
+                {
+                    RewriteResult mainProcessedAssembly = processedAssemblies.FirstOrDefault(p => p.OriginalAssemblyPath == Path.Combine(directory, manifest.EntryDll));
+                    if (mainProcessedAssembly == null)
+                    {
+                        Program.Monitor.Log($"{errorPrefix}: the specified mod DLL does not exist.", LogLevel.Error);
+                        continue;
+                    }
+                    mainAssemblyPath = forceUseCachedAssembly ? mainProcessedAssembly.CachePaths.Assembly : mainProcessedAssembly.OriginalAssemblyPath;
+                }
+
+                // load entry assembly
                 Assembly modAssembly;
                 try
                 {
-                    string assemblyPath = Path.Combine(directory, manifest.EntryDll);
-                    modAssembly = modAssemblyLoader.LoadCachedAssembly(assemblyPath);
+                    modAssembly = Assembly.UnsafeLoadFrom(mainAssemblyPath); // unsafe load allows downloaded DLLs
                     if (modAssembly.DefinedTypes.Count(x => x.BaseType == typeof(Mod)) == 0)
                     {
                         Program.Monitor.Log($"{errorPrefix}: the mod DLL does not contain an implementation of the 'Mod' class.", LogLevel.Error);
diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj
index 96eb038e..8a827ace 100644
--- a/src/StardewModdingAPI/StardewModdingAPI.csproj
+++ b/src/StardewModdingAPI/StardewModdingAPI.csproj
@@ -154,8 +154,10 @@
     <Compile Include="Events\PlayerEvents.cs" />
     <Compile Include="Events\TimeEvents.cs" />
     <Compile Include="Extensions.cs" />
+    <Compile Include="Framework\AssemblyRewriting\RewriteResult.cs" />
     <Compile Include="Framework\AssemblyRewriting\CachePaths.cs" />
     <Compile Include="Framework\AssemblyRewriting\AssemblyTypeRewriter.cs" />
+    <Compile Include="Framework\AssemblyRewriting\CacheEntry.cs" />
     <Compile Include="Framework\DeprecationLevel.cs" />
     <Compile Include="Framework\DeprecationManager.cs" />
     <Compile Include="Framework\InternalExtensions.cs" />