Merge remote-tracking branch 'origin/master' into api14-rollup

Dalamud/Plugin/Internal/PluginManager.cs

@@ -362,6 +362,9 @@ internal class PluginManager : IInternalDisposableService
         if (!this.configuration.DoPluginTest)
             return false;
 
+        if (!manifest.TestingDalamudApiLevel.HasValue)
+            return false;
+
         return manifest.IsTestingExclusive || manifest.IsAvailableForTesting;
     }
 

Dalamud/Plugin/SelfTest/Internal/SelfTestRegistryPluginScoped.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using Dalamud.IoC;
 using Dalamud.IoC.Internal;
 using Dalamud.Plugin.Internal.Types;
+using Dalamud.Plugin.Services;
 
 namespace Dalamud.Plugin.SelfTest.Internal;
 
@@ -12,7 +13,7 @@ namespace Dalamud.Plugin.SelfTest.Internal;
 [PluginInterface]
 [ServiceManager.ScopedService]
 [ResolveVia<ISelfTestRegistry>]
-internal class SelfTestRegistryPluginScoped : ISelfTestRegistry, IInternalDisposableService
+internal class SelfTestRegistryPluginScoped : ISelfTestRegistry, IInternalDisposableService, IDalamudService
 {
     [ServiceManager.ServiceDependency]
     private readonly SelfTestRegistry selfTestRegistry = Service<SelfTestRegistry>.Get();

Dalamud/Plugin/Services/IReliableFileStorage.cs

@@ -0,0 +1,168 @@
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+
+using Dalamud.Configuration;
+using Dalamud.Storage;
+
+namespace Dalamud.Plugin.Services;
+
+/// <summary>
+/// Service to interact with the file system, as a replacement for standard C# file I/O.
+/// Writes and reads using this service are, to the best of our ability, atomic and reliable.
+///
+/// All data is synced to disk immediately and written to a database, additionally to files on disk. This means
+/// that in case of file corruption, data can likely be recovered from the database.
+///
+/// However, this also means that operations using this service duplicate data on disk, so we don't recommend
+/// performing large file operations. The service will not permit files larger than <see cref="MaxFileSizeBytes"/>
+/// (64MB) to be written.
+///
+/// Saved configuration data using the <see cref="PluginConfigurations"/> class uses this functionality implicitly.
+/// </summary>
+[Experimental("Dalamud001")]
+public interface IReliableFileStorage : IDalamudService
+{
+    /// <summary>
+    /// Gets the maximum file size, in bytes, that can be written using this service.
+    /// </summary>
+    /// <remarks>
+    /// The service enforces this limit when writing files and fails with an appropriate exception
+    /// (for example <see cref="ArgumentException"/> or a custom exception) when a caller attempts to write
+    /// more than this number of bytes.
+    /// </remarks>
+    long MaxFileSizeBytes { get; }
+
+    /// <summary>
+    /// Check whether a file exists either on the local filesystem or in the transparent backup database.
+    /// </summary>
+    /// <param name="path">The file system path to check. Must not be null or empty.</param>
+    /// <returns>
+    /// True if the file exists on disk or a backup copy exists in the storage's internal journal/backup database;
+    /// otherwise false.
+    /// </returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    bool Exists(string path);
+
+    /// <summary>
+    /// Write the given text into a file using UTF-8 encoding. The write is performed atomically and is persisted to
+    /// both the filesystem and the internal backup database used by this service.
+    /// </summary>
+    /// <param name="path">The file path to write to. Must not be null or empty.</param>
+    /// <param name="contents">The string contents to write. May be null, in which case an empty file is written.</param>
+    /// <returns>A <see cref="Task"/> that completes when the write has finished and been flushed to disk and the backup.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    Task WriteAllTextAsync(string path, string? contents);
+
+    /// <summary>
+    /// Write the given text into a file using the provided <paramref name="encoding"/>. The write is performed
+    /// atomically (to the extent possible) and is persisted to both the filesystem and the internal backup database
+    /// used by this service.
+    /// </summary>
+    /// <param name="path">The file path to write to. Must not be null or empty.</param>
+    /// <param name="contents">The string contents to write. May be null, in which case an empty file is written.</param>
+    /// <param name="encoding">The text encoding to use when serializing the string to bytes. Must not be null.</param>
+    /// <returns>A <see cref="Task"/> that completes when the write has finished and been flushed to disk and the backup.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="encoding"/> is null.</exception>
+    Task WriteAllTextAsync(string path, string? contents, Encoding encoding);
+
+    /// <summary>
+    /// Write the given bytes to a file. The write is persisted to both the filesystem and the service's internal
+    /// backup database. Avoid writing extremely large byte arrays because this service duplicates data on disk.
+    /// </summary>
+    /// <param name="path">The file path to write to. Must not be null or empty.</param>
+    /// <param name="bytes">The raw bytes to write. Must not be null.</param>
+    /// <returns>A <see cref="Task"/> that completes when the write has finished and been flushed to disk and the backup.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="bytes"/> is null.</exception>
+    Task WriteAllBytesAsync(string path, byte[] bytes);
+
+    /// <summary>
+    /// Read all text from a file using UTF-8 encoding. If the file is unreadable or missing on disk, the service
+    /// attempts to return a backed-up copy from its internal journal/backup database.
+    /// </summary>
+    /// <param name="path">The file path to read. Must not be null or empty.</param>
+    /// <param name="forceBackup">
+    /// When true the service prefers the internal backup database and returns backed-up contents if available. When
+    /// false the service tries the filesystem first and falls back to the backup only on error or when the file is missing.
+    /// </param>
+    /// <returns>The textual contents of the file, decoded using UTF-8.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the file does not exist on disk and no backup copy is available.</exception>
+    Task<string> ReadAllTextAsync(string path, bool forceBackup = false);
+
+    /// <summary>
+    /// Read all text from a file using the specified <paramref name="encoding"/>. If the file is unreadable or
+    /// missing on disk, the service attempts to return a backed-up copy from its internal journal/backup database.
+    /// </summary>
+    /// <param name="path">The file path to read. Must not be null or empty.</param>
+    /// <param name="encoding">The encoding to use when decoding the stored bytes into text. Must not be null.</param>
+    /// <param name="forceBackup">
+    /// When true the service prefers the internal backup database and returns backed-up contents if available. When
+    /// false the service tries the filesystem first and falls back to the backup only on error or when the file is missing.
+    /// </param>
+    /// <returns>The textual contents of the file decoded using the provided <paramref name="encoding"/>.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="encoding"/> is null.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the file does not exist on disk and no backup copy is available.</exception>
+    Task<string> ReadAllTextAsync(string path, Encoding encoding, bool forceBackup = false);
+
+    /// <summary>
+    /// Read all text from a file and invoke the provided <paramref name="reader"/> callback with the string
+    /// contents. If the reader throws or the initial read fails, the service attempts a backup read and invokes the
+    /// reader again with the backup contents. If both reads fail the service surfaces an exception to the caller.
+    /// </summary>
+    /// <param name="path">The file path to read. Must not be null or empty.</param>
+    /// <param name="reader">
+    /// A callback invoked with the file's textual contents. Must not be null.
+    /// If the callback throws an exception the service treats that as a signal to retry the read using the
+    /// internal backup database and will invoke the callback again with the backup contents when available.
+    /// For example, the callback can throw when JSON deserialization fails to request the backup copy instead of
+    /// silently accepting corrupt data.
+    /// </param>
+    /// <returns>A <see cref="Task"/> that completes when the read (and any attempted fallback) and callback invocation have finished.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="reader"/> is null.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the file does not exist on disk and no backup copy is available.</exception>
+    /// <exception cref="FileReadException">Thrown when both the filesystem read and the backup read fail for other reasons.</exception>
+    Task ReadAllTextAsync(string path, Action<string> reader);
+
+    /// <summary>
+    /// Read all text from a file using the specified <paramref name="encoding"/> and invoke the provided
+    /// <paramref name="reader"/> callback with the decoded string contents. If the reader throws or the initial
+    /// read fails, the service attempts a backup read and invokes the reader again with the backup contents. If
+    /// both reads fail the service surfaces an exception to the caller.
+    /// </summary>
+    /// <param name="path">The file path to read. Must not be null or empty.</param>
+    /// <param name="encoding">The encoding to use when decoding the stored bytes into text. Must not be null.</param>
+    /// <param name="reader">
+    /// A callback invoked with the file's textual contents. Must not be null.
+    /// If the callback throws an exception the service treats that as a signal to retry the read using the
+    /// internal backup database and will invoke the callback again with the backup contents when available.
+    /// For example, the callback can throw when JSON deserialization fails to request the backup copy instead of
+    /// silently accepting corrupt data.
+    /// </param>
+    /// <returns>A <see cref="Task"/> that completes when the read (and any attempted fallback) and callback invocation have finished.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="encoding"/> or <paramref name="reader"/> is null.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the file does not exist on disk and no backup copy is available.</exception>
+    /// <exception cref="FileReadException">Thrown when both the filesystem read and the backup read fail for other reasons.</exception>
+    Task ReadAllTextAsync(string path, Encoding encoding, Action<string> reader);
+
+    /// <summary>
+    /// Read all bytes from a file. If the file is unreadable or missing on disk, the service may try to return a
+    /// backed-up copy from its internal journal/backup database.
+    /// </summary>
+    /// <param name="path">The file path to read. Must not be null or empty.</param>
+    /// <param name="forceBackup">
+    /// When true the service prefers the internal backup database and returns the backed-up contents
+    /// if available. When false the service tries the filesystem first and falls back to the backup only
+    /// on error or when the file is missing.
+    /// </param>
+    /// <returns>The raw bytes stored in the file.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is null or empty.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the file does not exist on disk and no backup copy is available.</exception>
+    Task<byte[]> ReadAllBytesAsync(string path, bool forceBackup = false);
+}

Dalamud/Plugin/Services/IUnlockState.cs

@@ -10,7 +10,7 @@ namespace Dalamud.Plugin.Services;
 /// <summary>
 /// Interface for determining unlock state of various content in the game.
 /// </summary>
-[Experimental("UnlockState")]
+[Experimental("Dalamud001")]
 public interface IUnlockState : IDalamudService
 {
     /// <summary>