diff --git a/src/GameCult.Caching.MessagePack/CultCacheMessagePack.cs b/src/GameCult.Caching.MessagePack/CultCacheMessagePack.cs
index 02ee32d5..e464e5e6 100644
--- a/src/GameCult.Caching.MessagePack/CultCacheMessagePack.cs
+++ b/src/GameCult.Caching.MessagePack/CultCacheMessagePack.cs
@@ -4,54 +4,27 @@ using System.Threading.Tasks;
namespace GameCult.Caching.MessagePack
{
- ///
- /// Options for opening a CultCache over the canonical single-file MessagePack backing store.
- ///
public sealed class CultCacheOpenOptions
{
- ///
- /// Gets or sets the document registry to use. When omitted, the shared registry is used.
- ///
public CultDocumentRegistry? Registry { get; set; }
- ///
- /// Gets or sets whether the cache should pull the existing snapshot during open.
- ///
public bool PullOnOpen { get; set; } = true;
- ///
- /// Gets or sets whether the cache should flush attached stores when disposed.
- ///
public bool FlushOnDispose { get; set; }
- ///
- /// Gets or sets whether the backing store should flush when disposed.
- ///
public bool StoreFlushOnDispose { get; set; }
- ///
- /// Gets or sets whether the cache should use a paged directory store instead of one whole-file snapshot.
- ///
public bool UseDirectoryStore { get; set; }
}
- ///
- /// Friendly MessagePack entrypoints for opening a CultCache with the canonical backing store.
- ///
public static class CultCacheMessagePack
{
- ///
- /// Creates a cache with the canonical single-file MessagePack backing store attached.
- ///
public static CultCache Create(string filePath, CultCacheOpenOptions? options = null)
{
options ??= new CultCacheOpenOptions();
return CreateCore(filePath, options, initializeGlobals: true);
}
- ///
- /// Creates a cache with the canonical single-file MessagePack backing store attached and optionally pulls the on-disk snapshot.
- ///
public static async Task OpenAsync(string filePath, CultCacheOpenOptions? options = null)
{
options ??= new CultCacheOpenOptions();
diff --git a/src/GameCult.Caching.MessagePack/CultDocumentMessagePackSerialization.cs b/src/GameCult.Caching.MessagePack/CultDocumentMessagePackSerialization.cs
index fe9519b9..b5a621fb 100644
--- a/src/GameCult.Caching.MessagePack/CultDocumentMessagePackSerialization.cs
+++ b/src/GameCult.Caching.MessagePack/CultDocumentMessagePackSerialization.cs
@@ -7,20 +7,11 @@ using MessagePack.Resolvers;
namespace GameCult.Caching.MessagePack;
-///
-/// MessagePack resolver for CultCache-specific value types.
-///
public sealed class CultDocumentResolver : IFormatterResolver
{
- ///
- /// Gets the shared resolver instance.
- ///
public static readonly CultDocumentResolver Instance = new();
private CultDocumentResolver() { }
- ///
- /// Gets a formatter for the requested type, when this resolver owns it.
- ///
public IMessagePackFormatter? GetFormatter()
{
var type = typeof(T);
@@ -34,9 +25,6 @@ public sealed class CultDocumentResolver : IFormatterResolver
}
}
-///
-/// MessagePack serialization helpers for CultCache documents and backing stores.
-///
public static class CultDocumentMessagePackSerialization
{
private const int PersistedRecordFieldCount = 4;
@@ -44,9 +32,6 @@ public static class CultDocumentMessagePackSerialization
private const int SchemaCatalogMemberFieldCount = 8;
private const int StoreSnapshotFieldCount = 3;
- ///
- /// Gets the shared MessagePack serializer options for CultCache payloads.
- ///
public static readonly MessagePackSerializerOptions Options =
MessagePackSerializerOptions.Standard
.WithResolver(CompositeResolver.Create(
@@ -54,33 +39,21 @@ public static class CultDocumentMessagePackSerialization
StandardResolver.Instance))
.WithSecurity(MessagePackSecurity.UntrustedData);
- ///
- /// Serializes a typed value with the CultCache MessagePack options.
- ///
public static byte[] Serialize(T value)
{
return MessagePackSerializer.Serialize(value, Options);
}
- ///
- /// Deserializes a typed value with the CultCache MessagePack options.
- ///
public static T Deserialize(byte[] payload)
{
return MessagePackSerializer.Deserialize(payload, Options);
}
- ///
- /// Serializes a value whose document type is known at runtime.
- ///
public static byte[] SerializeUntyped(object value, Type type)
{
return SerializeUntyped(value, type, CultDocumentRegistry.Shared);
}
- ///
- /// Serializes a value through an explicitly owned document registry.
- ///
public static byte[] SerializeUntyped(object value, Type type, CultDocumentRegistry registry)
{
if (registry == null) throw new ArgumentNullException(nameof(registry));
@@ -96,17 +69,11 @@ public static class CultDocumentMessagePackSerialization
return MessagePackSerializer.Serialize(type, value, Options);
}
- ///
- /// Deserializes a value whose document type is known at runtime.
- ///
public static object DeserializeUntyped(Type type, byte[] payload)
{
return DeserializeUntyped(type, payload, CultDocumentRegistry.Shared);
}
- ///
- /// Deserializes a value through an explicitly owned document registry.
- ///
public static object DeserializeUntyped(Type type, byte[] payload, CultDocumentRegistry registry)
{
if (registry == null) throw new ArgumentNullException(nameof(registry));
@@ -120,9 +87,6 @@ public static class CultDocumentMessagePackSerialization
?? throw new InvalidOperationException($"MessagePack returned null for Cult document type {type.FullName}.");
}
- ///
- /// Serializes one persisted store record.
- ///
public static byte[] SerializePersistedRecord(CultPersistedRecord record)
{
var buffer = new global::System.Buffers.ArrayBufferWriter();
@@ -132,18 +96,12 @@ public static class CultDocumentMessagePackSerialization
return buffer.WrittenSpan.ToArray();
}
- ///
- /// Deserializes one persisted store record.
- ///
public static CultPersistedRecord DeserializePersistedRecord(byte[] payload)
{
var reader = new MessagePackReader(payload);
return ReadPersistedRecord(ref reader);
}
- ///
- /// Serializes a complete persisted store snapshot.
- ///
public static byte[] SerializeSnapshot(CultPersistedStoreSnapshot snapshot)
{
var buffer = new global::System.Buffers.ArrayBufferWriter();
@@ -166,9 +124,6 @@ public static class CultDocumentMessagePackSerialization
return buffer.WrittenSpan.ToArray();
}
- ///
- /// Deserializes a complete persisted store snapshot.
- ///
public static CultPersistedStoreSnapshot DeserializeSnapshot(byte[] payload)
{
var reader = new MessagePackReader(payload);
@@ -396,45 +351,27 @@ public static class CultDocumentMessagePackSerialization
}
}
-///
-/// Single-file CultCache backing store that persists snapshots as MessagePack.
-///
public class SingleFileMessagePackBackingStore : SingleFileBackingStore
{
- ///
- /// Creates a MessagePack single-file backing store.
- ///
public SingleFileMessagePackBackingStore(string filePath) : base(filePath)
{
}
- ///
- /// Serializes a store snapshot.
- ///
protected override byte[] SerializeSnapshot(CultPersistedStoreSnapshot snapshot)
{
return CultDocumentMessagePackSerialization.SerializeSnapshot(snapshot);
}
- ///
- /// Deserializes a store snapshot.
- ///
protected override CultPersistedStoreSnapshot DeserializeSnapshot(byte[] data)
{
return CultDocumentMessagePackSerialization.DeserializeSnapshot(data);
}
- ///
- /// Serializes one document payload.
- ///
protected override byte[] SerializePayload(object document)
{
return CultDocumentMessagePackSerialization.SerializeUntyped(document, document.GetType(), Registry);
}
- ///
- /// Deserializes one document payload.
- ///
protected override object DeserializePayload(Type documentType, byte[] payload)
{
return CultDocumentMessagePackSerialization.DeserializeUntyped(documentType, payload, Registry);
diff --git a/src/GameCult.Caching.MessagePack/CultRecordRefFormatter.cs b/src/GameCult.Caching.MessagePack/CultRecordRefFormatter.cs
index 3348c1c3..a5f984fc 100644
--- a/src/GameCult.Caching.MessagePack/CultRecordRefFormatter.cs
+++ b/src/GameCult.Caching.MessagePack/CultRecordRefFormatter.cs
@@ -3,22 +3,13 @@ using MessagePack.Formatters;
namespace GameCult.Caching;
-///
-/// Serializes typed CultCache record references as their persisted key strings.
-///
public sealed class CultRecordRefFormatter : IMessagePackFormatter>
{
- ///
- /// Writes a typed record reference to MessagePack.
- ///
public void Serialize(ref MessagePackWriter writer, CultRecordRef value, MessagePackSerializerOptions options)
{
options.Resolver.GetFormatterWithVerify().Serialize(ref writer, value.Key.Value, options);
}
- ///
- /// Reads a typed record reference from MessagePack.
- ///
public CultRecordRef Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
{
var key = options.Resolver.GetFormatterWithVerify().Deserialize(ref reader, options) ?? string.Empty;
diff --git a/src/GameCult.Caching.MessagePack/DirectoryMessagePackBackingStore.cs b/src/GameCult.Caching.MessagePack/DirectoryMessagePackBackingStore.cs
index 0e6ab7bb..fd8d3c26 100644
--- a/src/GameCult.Caching.MessagePack/DirectoryMessagePackBackingStore.cs
+++ b/src/GameCult.Caching.MessagePack/DirectoryMessagePackBackingStore.cs
@@ -11,9 +11,6 @@ using MessagePack;
namespace GameCult.Caching.MessagePack;
-///
-/// MessagePack backing store that keeps a small schema manifest hot and stores each record as its own cold file.
-///
public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
{
private const string IndexedFormatVersion = "cultcache.store.v4.directory-content-addressed-pages";
@@ -26,9 +23,6 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
private Dictionary _durableIndex = new(StringComparer.Ordinal);
private CultSchemaCatalogEntry[] _durableCatalog = Array.Empty();
- ///
- /// Creates a paged MessagePack backing store.
- ///
public DirectoryMessagePackBackingStore(string manifestPath, string? recordDirectoryPath = null)
{
if (string.IsNullOrWhiteSpace(manifestPath))
@@ -40,12 +34,8 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
_recordDirectory = new DirectoryInfo(recordDirectoryPath ?? DefaultRecordDirectoryPath(manifestPath));
}
- ///
- /// Gets the default record directory path for a manifest path.
- ///
public static string DefaultRecordDirectoryPath(string manifestPath) => manifestPath + ".records";
- ///
public override void PullAll()
{
lock (_mutationGate)
@@ -120,14 +110,12 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
Trace("publish");
}
- ///
public override bool ContainsDurableRecord(CultRecordKey key)
{
lock (_mutationGate)
return _durableIndex.ContainsKey(key.Value) || base.ContainsDurableRecord(key);
}
- ///
public override void Push(CultStoredDocument entry)
{
lock (_mutationGate)
@@ -139,7 +127,6 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
}
}
- ///
public override void Delete(CultStoredDocument entry)
{
lock (_mutationGate)
@@ -151,7 +138,6 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
}
}
- ///
public override void CommitBatch(
IReadOnlyCollection upserts,
IReadOnlyCollection deletes)
@@ -196,7 +182,6 @@ public sealed class DirectoryMessagePackBackingStore : CacheBackingStore
}
}
- ///
public override void PushAll()
{
lock (_mutationGate)
diff --git a/src/GameCult.Caching.MessagePack/GameCult.Caching.MessagePack.csproj b/src/GameCult.Caching.MessagePack/GameCult.Caching.MessagePack.csproj
index 71fcc969..24e7a48e 100644
--- a/src/GameCult.Caching.MessagePack/GameCult.Caching.MessagePack.csproj
+++ b/src/GameCult.Caching.MessagePack/GameCult.Caching.MessagePack.csproj
@@ -1,6 +1,7 @@
File-based MessagePack backing store for CultCache
+ $(NoWarn);CS1591
diff --git a/src/GameCult.Caching/CultCache.cs b/src/GameCult.Caching/CultCache.cs
index 84b5e869..8cf59d40 100644
--- a/src/GameCult.Caching/CultCache.cs
+++ b/src/GameCult.Caching/CultCache.cs
@@ -13,205 +13,82 @@ using R3;
namespace GameCult.Caching
{
- ///
- /// Persisted schema metadata embedded in a CultCache backing store.
- ///
public sealed class CultSchemaCatalogEntry
{
- ///
- /// Gets or sets the content-derived schema identifier.
- ///
public string SchemaId { get; set; } = string.Empty;
- ///
- /// Gets or sets the stable schema name.
- ///
public string SchemaName { get; set; } = string.Empty;
- ///
- /// Gets or sets the schema version string.
- ///
public string SchemaVersion { get; set; } = string.Empty;
- ///
- /// Gets or sets the canonical schema content hash.
- ///
public string ContentHash { get; set; } = string.Empty;
- ///
- /// Gets or sets the canonical schema description.
- ///
public string CanonicalSchemaJson { get; set; } = string.Empty;
- ///
- /// Gets or sets schema identifiers compatible with this entry.
- ///
public string[] CompatibleSchemaIds { get; set; } = Array.Empty();
- ///
- /// Gets or sets the persisted member descriptors used for compatibility checks.
- ///
public CultSchemaMemberCatalogEntry[] Members { get; set; } = Array.Empty();
}
- ///
- /// Persisted catalog entry describing one schema member.
- ///
public sealed class CultSchemaMemberCatalogEntry
{
- ///
- /// Gets or sets the persisted slot number.
- ///
public int Slot { get; set; }
- ///
- /// Gets or sets the member name.
- ///
public string MemberName { get; set; } = string.Empty;
- ///
- /// Gets or sets the persisted type name.
- ///
public string TypeName { get; set; } = string.Empty;
- ///
- /// Gets or sets whether the member is a reference.
- ///
public bool IsReference { get; set; }
- ///
- /// Gets or sets whether the member stores many values.
- ///
public bool IsMany { get; set; }
- ///
- /// Gets or sets the referenced schema name, when the member is a reference.
- ///
public string? TargetSchemaName { get; set; }
- ///
- /// Gets or sets whether the member provides the name lookup.
- ///
public bool IsName { get; set; }
- ///
- /// Gets or sets the index alias, when the member participates in lookups.
- ///
public string? IndexAlias { get; set; }
}
- ///
- /// Persisted serialized document record.
- ///
public sealed class CultPersistedRecord
{
- ///
- /// Gets or sets the persisted record key.
- ///
public string Key { get; set; } = string.Empty;
- ///
- /// Gets or sets the schema identifier used to deserialize the payload.
- ///
public string SchemaId { get; set; } = string.Empty;
- ///
- /// Gets or sets the storage timestamp.
- ///
public string StoredAt { get; set; } = string.Empty;
- ///
- /// Gets or sets the serialized document payload.
- ///
public byte[] Payload { get; set; } = Array.Empty();
}
- ///
- /// Complete snapshot persisted by a single-file CultCache backing store.
- ///
public sealed class CultPersistedStoreSnapshot
{
- ///
- /// Gets or sets the backing store format version.
- ///
public string FormatVersion { get; set; } = "cultcache.store.v1";
- ///
- /// Gets or sets the embedded schema catalog.
- ///
public CultSchemaCatalogEntry[] SchemaCatalog { get; set; } = Array.Empty();
- ///
- /// Gets or sets the persisted records.
- ///
public CultPersistedRecord[] Records { get; set; } = Array.Empty();
}
- ///
- /// Classifies how a persisted schema mapped onto the local document registry.
- ///
public enum CultSchemaMigrationKind
{
- ///
- /// The persisted schema matched the local schema exactly.
- ///
Exact,
- ///
- /// The persisted schema required a compatible soft-migration path.
- ///
CompatibleDrift
}
- ///
- /// Describes one schema-resolution warning emitted during load.
- ///
public sealed class CultSchemaMigrationWarning
{
- ///
- /// Gets or sets the stable warning code.
- ///
public string Code { get; set; } = string.Empty;
- ///
- /// Gets or sets the human-readable warning text.
- ///
public string Message { get; set; } = string.Empty;
}
- ///
- /// Reports how one persisted schema entry resolved against the local schema catalog.
- ///
public sealed class CultSchemaMigrationReport
{
- ///
- /// Gets or sets the persisted schema identifier.
- ///
public string PersistedSchemaId { get; set; } = string.Empty;
- ///
- /// Gets or sets the local schema identifier selected for reading.
- ///
public string LocalSchemaId { get; set; } = string.Empty;
- ///
- /// Gets or sets the persisted schema name.
- ///
public string PersistedSchemaName { get; set; } = string.Empty;
- ///
- /// Gets or sets the local schema name.
- ///
public string LocalSchemaName { get; set; } = string.Empty;
- ///
- /// Gets or sets how the persisted schema matched locally.
- ///
public CultSchemaMigrationKind Kind { get; set; }
- ///
- /// Gets or sets the persisted member slots ignored by the local reader.
- ///
public int[] IgnoredExtraSlots { get; set; } = Array.Empty();
- ///
- /// Gets or sets the local member slots defaulted because the persisted record did not contain them.
- ///
public int[] DefaultedMissingSlots { get; set; } = Array.Empty();
- ///
- /// Gets or sets emitted migration warnings.
- ///
public CultSchemaMigrationWarning[] Warnings { get; set; } = Array.Empty();
}
@@ -228,9 +105,6 @@ namespace GameCult.Caching
public CultSchemaMigrationReport Report { get; }
}
- ///
- /// Runtime descriptor for a CultCache document type.
- ///
public sealed class CultDocumentDescriptor
{
internal CultDocumentDescriptor(
@@ -263,53 +137,20 @@ namespace GameCult.Caching
Members = members;
}
- ///
- /// Gets the CLR document type.
- ///
public Type DocumentType { get; }
- ///
- /// Gets the stable schema name.
- ///
public string SchemaName { get; }
- ///
- /// Gets the schema version string.
- ///
public string SchemaVersion { get; }
- ///
- /// Gets the content-derived schema identifier.
- ///
public string SchemaId { get; }
- ///
- /// Gets the canonical schema content hash.
- ///
public string ContentHash { get; }
- ///
- /// Gets the canonical schema description.
- ///
public string CanonicalSchemaJson { get; }
- ///
- /// Gets whether this document type stores one global record.
- ///
public bool IsGlobal { get; }
- ///
- /// Gets the document name member, if any.
- ///
public string? NameMember { get; }
internal Func