using System; using System.IO; using System.Linq; using System.Security.Cryptography; using GameCult.Caching; using GameCult.Caching.MessagePack; namespace GameCult.Mesh { /// /// Schema metadata used when publishing one raw document payload as a CultCache single-file snapshot. /// public sealed class CultMeshSingleFileDocumentSchema { /// /// Creates schema metadata for a single-file document publication. /// public CultMeshSingleFileDocumentSchema(string schemaId, string schemaName, string schemaVersion) { if (string.IsNullOrWhiteSpace(schemaId)) throw new ArgumentException("Value must be non-empty.", nameof(schemaId)); if (string.IsNullOrWhiteSpace(schemaName)) throw new ArgumentException("Value must be non-empty.", nameof(schemaName)); if (string.IsNullOrWhiteSpace(schemaVersion)) throw new ArgumentException("Value must be non-empty.", nameof(schemaVersion)); SchemaId = schemaId; SchemaName = schemaName; SchemaVersion = schemaVersion; } /// /// Gets the content-derived schema identifier. /// public string SchemaId { get; } /// /// Gets the stable schema name. /// public string SchemaName { get; } /// /// Gets the schema version. /// public string SchemaVersion { get; } /// /// Gets or sets an optional canonical schema description. /// public string CanonicalSchemaJson { get; set; } = string.Empty; /// /// Gets or sets compatible schema identifiers accepted for this document. /// public string[] CompatibleSchemaIds { get; set; } = Array.Empty(); internal CultSchemaCatalogEntry ToCatalogEntry(byte[] payload) { return new CultSchemaCatalogEntry { SchemaId = SchemaId, SchemaName = SchemaName, SchemaVersion = SchemaVersion, ContentHash = StableHash(payload), CanonicalSchemaJson = CanonicalSchemaJson, CompatibleSchemaIds = CompatibleSchemaIds .Append(SchemaId) .Where(candidate => !string.IsNullOrWhiteSpace(candidate)) .Distinct(StringComparer.Ordinal) .ToArray(), Members = Array.Empty() }; } private static string StableHash(byte[] payload) { if (payload == null || payload.Length == 0) return "empty"; using var sha = SHA256.Create(); return BitConverter.ToString(sha.ComputeHash(payload)).Replace("-", "", StringComparison.Ordinal).ToLowerInvariant(); } } public static partial class CultMesh { /// /// Writes one typed document as a canonical single-file MessagePack CultCache snapshot. /// public static void WriteSingleFileDocument( string path, CultRecordKey key, TDocument document, string? storedAt = null, CultDocumentRegistry? registry = null) where TDocument : class { if (document == null) throw new ArgumentNullException(nameof(document)); var resolvedRegistry = registry ?? CultDocumentRegistry.Shared; var descriptor = resolvedRegistry.GetRequired(); // Element ids are decided as a cache write decides them, before anything is written: an unset id is minted, a // refused list refuses the write, and the file is marked when it holds an id. A failed write gives the ids back. var ids = CultElementIds.Plan(document, key.Value, deterministic: false); ids.Apply(); try { WriteSingleFileDocumentPayload( path, key, descriptor.ToCatalogEntry(), storedAt, CultDocumentMessagePackSerialization.SerializeUntyped(document, typeof(TDocument)), CultElementIds.Holds(document), contentKnown: true); } catch { ids.Undo(); throw; } } /// /// Reads one typed document from a single-file MessagePack CultCache snapshot. /// public static TDocument ReadSingleFileDocument( string path, CultRecordKey key, CultDocumentRegistry? registry = null) where TDocument : class { var resolvedRegistry = registry ?? CultDocumentRegistry.Shared; var descriptor = resolvedRegistry.GetRequired(); var payload = ReadSingleFileDocumentPayload(path, key, descriptor.SchemaId); var document = (TDocument)CultDocumentMessagePackSerialization.DeserializeUntyped(typeof(TDocument), payload); // A load refuses what a write refuses, and mints the ids a cache load of the same file would mint. CultElementIds.Plan(document, key.Value, deterministic: true).Apply(); return document; } /// /// Writes one raw document payload as a canonical single-file MessagePack CultCache snapshot. /// public static void WriteSingleFileDocumentPayload( string path, CultRecordKey key, CultMeshSingleFileDocumentSchema schema, string? storedAt, byte[] payload) { if (schema == null) throw new ArgumentNullException(nameof(schema)); WriteSingleFileDocumentPayload(path, key, schema.ToCatalogEntry(payload), storedAt, payload, holdsIds: false, contentKnown: false); } /// /// Reads one raw document payload from a single-file MessagePack CultCache snapshot. /// public static byte[] ReadSingleFileDocumentPayload( string path, CultRecordKey key, string expectedSchemaId) { if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path)); if (string.IsNullOrWhiteSpace(expectedSchemaId)) throw new ArgumentException("Value must be non-empty.", nameof(expectedSchemaId)); var snapshot = ReadSingleFileSnapshot(path); var record = snapshot.Records.SingleOrDefault(candidate => string.Equals(candidate.Key, key.Value, StringComparison.Ordinal)) ?? throw new InvalidDataException($"CultCache document '{path}' does not contain record '{key.Value}'."); if (!string.Equals(record.SchemaId, expectedSchemaId, StringComparison.Ordinal)) { throw new InvalidDataException( $"CultCache document '{path}' record '{key.Value}' has schema '{record.SchemaId}', expected '{expectedSchemaId}'."); } RefuseVariant(path, record); if (!PublishesSchema(snapshot.SchemaCatalog, expectedSchemaId)) { throw new InvalidDataException( $"CultCache document '{path}' does not publish schema '{expectedSchemaId}' in its catalog."); } return record.Payload; } /// /// Reads the only raw document payload from a single-file MessagePack CultCache snapshot. /// public static byte[] ReadSingleFileDocumentPayload( string path, string expectedSchemaId) { if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path)); if (string.IsNullOrWhiteSpace(expectedSchemaId)) throw new ArgumentException("Value must be non-empty.", nameof(expectedSchemaId)); var snapshot = ReadSingleFileSnapshot(path); if (snapshot.Records.Length != 1) { throw new InvalidDataException( $"CultCache document '{path}' must contain exactly one record."); } var record = snapshot.Records[0]; if (!string.Equals(record.SchemaId, expectedSchemaId, StringComparison.Ordinal)) { throw new InvalidDataException( $"CultCache document '{path}' has schema '{record.SchemaId}', expected '{expectedSchemaId}'."); } if (!PublishesSchema(snapshot.SchemaCatalog, expectedSchemaId)) { throw new InvalidDataException( $"CultCache document '{path}' does not publish schema '{expectedSchemaId}' in its catalog."); } return record.Payload; } // A variant record's payload is empty; its document exists only as the cache resolves it against its base. private static void RefuseVariant(string path, CultPersistedRecord record) { if (record.Variant != null) throw new NotSupportedException( $"CultCache document '{path}' record '{record.Key}' is a variant of '{record.Variant.BaseKey}'; " + "CultMesh does not resolve document variants, open the store with a CultCache."); } private static void WriteSingleFileDocumentPayload( string path, CultRecordKey key, CultSchemaCatalogEntry catalogEntry, string? storedAt, byte[] payload, bool holdsIds, bool contentKnown) { if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path)); if (catalogEntry == null) throw new ArgumentNullException(nameof(catalogEntry)); if (string.IsNullOrWhiteSpace(catalogEntry.SchemaId)) throw new ArgumentException("Catalog entry must include a schema id.", nameof(catalogEntry)); payload ??= Array.Empty(); CultPersistedStoreSnapshot? existing = null; // A typed write sees the document it replaces the file with, so its ids decide. A raw payload is opaque: the writer // cannot see whether it holds ids, so a file already marked stays marked. var snapshot = new CultPersistedStoreSnapshot { FormatVersion = CacheBackingStore.HeaderFor(holdsIds, existing?.FormatVersion, wholeStore: contentKnown, directoryStore: false), SchemaCatalog = new[] { catalogEntry }, Records = new[] { new CultPersistedRecord { Key = key.Value, SchemaId = catalogEntry.SchemaId, StoredAt = string.IsNullOrWhiteSpace(storedAt) ? DateTimeOffset.UtcNow.ToString("O") : storedAt!, Payload = payload } } }; } private static bool PublishesSchema(CultSchemaCatalogEntry[] catalog, string schemaId) { return catalog.Any(entry => string.Equals(entry.SchemaId, schemaId, StringComparison.Ordinal) || entry.CompatibleSchemaIds.Any(candidate => string.Equals(candidate, schemaId, StringComparison.Ordinal))); } } }