From 1f40bbe411bc313f11643fb513878cc9d817276b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Mon, 13 Jul 2026 19:35:52 +0100 Subject: [PATCH] Address CultMesh body publications by generation --- src/GameCult.Mesh/CultMeshBodyPublications.cs | 50 ++++++++++++++++--- .../CultMeshBodyPublicationTests.cs | 50 +++++++++++++++++-- 2 files changed, 91 insertions(+), 9 deletions(-) diff --git a/src/GameCult.Mesh/CultMeshBodyPublications.cs b/src/GameCult.Mesh/CultMeshBodyPublications.cs index 8290db60..48d6e7b8 100644 --- a/src/GameCult.Mesh/CultMeshBodyPublications.cs +++ b/src/GameCult.Mesh/CultMeshBodyPublications.cs @@ -244,7 +244,26 @@ namespace GameCult.Mesh [Key(10)] public CultMeshBodyDescriptor PreferredLocal { get; set; } = new(); [Key(11)] public CultMeshBodyDescriptor NetworkFallback { get; set; } = new(); - public static CultRecordKey CreateRecordKey(string bodyId) + public static CultRecordKey CreateRecordKey(string bodyId, long producerEpoch, long sequence) + { + if (string.IsNullOrWhiteSpace(bodyId)) + throw new ArgumentException("Logical body identity is required.", nameof(bodyId)); + if (producerEpoch < 0) throw new ArgumentOutOfRangeException(nameof(producerEpoch)); + if (sequence < 0) throw new ArgumentOutOfRangeException(nameof(sequence)); + using var stream = new MemoryStream(); + using (var writer = new BinaryWriter(stream, Encoding.UTF8, leaveOpen: true)) + { + writer.Write(bodyId); + writer.Write(producerEpoch); + writer.Write(sequence); + } + using var sha256 = SHA256.Create(); + var generationId = string.Concat(sha256.ComputeHash(stream.ToArray()) + .Select(value => value.ToString("x2", CultureInfo.InvariantCulture))); + return new CultRecordKey("mesh:body-generation:" + generationId); + } + + public static CultRecordKey CreateLatestRecordKey(string bodyId) { if (string.IsNullOrWhiteSpace(bodyId)) throw new ArgumentException("Logical body identity is required.", nameof(bodyId)); @@ -252,35 +271,52 @@ namespace GameCult.Mesh } [IgnoreMember] - public CultRecordKey RecordKey => CreateRecordKey(BodyId); + public CultRecordKey RecordKey => CreateRecordKey(BodyId, ProducerEpoch, Sequence); } public sealed class CultMeshBodyPublicationHandle { - public CultMeshBodyPublicationHandle(string bodyId) + public CultMeshBodyPublicationHandle(string bodyId, long producerEpoch, long sequence) { BodyId = string.IsNullOrWhiteSpace(bodyId) ? throw new ArgumentException("Logical body identity is required.", nameof(bodyId)) : bodyId; - RecordKey = CultMeshBodyPublicationDocument.CreateRecordKey(bodyId); + ProducerEpoch = producerEpoch >= 0 + ? producerEpoch + : throw new ArgumentOutOfRangeException(nameof(producerEpoch)); + Sequence = sequence >= 0 + ? sequence + : throw new ArgumentOutOfRangeException(nameof(sequence)); + RecordKey = CultMeshBodyPublicationDocument.CreateRecordKey(bodyId, producerEpoch, sequence); } public string BodyId { get; } + public long ProducerEpoch { get; } + public long Sequence { get; } public CultRecordKey RecordKey { get; } public void Validate(CultMeshBodyPublicationDocument publication) => - CultMeshBodyPublicationValidator.Validate(publication, BodyId); + CultMeshBodyPublicationValidator.Validate(publication, BodyId, ProducerEpoch, Sequence, RecordKey); } public static class CultMeshBodyPublicationValidator { - public static void Validate(CultMeshBodyPublicationDocument publication, string? expectedBodyId = null) + public static void Validate( + CultMeshBodyPublicationDocument publication, + string? expectedBodyId = null, + long? expectedProducerEpoch = null, + long? expectedSequence = null, + CultRecordKey? expectedRecordKey = null) { if (publication == null) throw new ArgumentNullException(nameof(publication)); if (string.IsNullOrWhiteSpace(publication.BodyId)) throw new InvalidOperationException("CultMesh body publication has no logical body identity."); if (expectedBodyId != null && !string.Equals(publication.BodyId, expectedBodyId, StringComparison.Ordinal)) throw new InvalidOperationException("CultMesh body publication handle identity mismatch."); + if (expectedProducerEpoch.HasValue && publication.ProducerEpoch != expectedProducerEpoch.Value) + throw new InvalidOperationException("CultMesh body publication handle producer epoch mismatch."); + if (expectedSequence.HasValue && publication.Sequence != expectedSequence.Value) + throw new InvalidOperationException("CultMesh body publication handle sequence mismatch."); if (string.IsNullOrWhiteSpace(publication.ProducerId)) throw new InvalidOperationException("CultMesh body publication has no producer identity."); if (string.IsNullOrWhiteSpace(publication.SchemaId)) @@ -288,6 +324,8 @@ namespace GameCult.Mesh if (publication.LayoutVersion < 0 || publication.ByteSize < 0 || publication.Capacity < 0 || publication.ProducerEpoch < 0 || publication.Sequence < 0) throw new InvalidOperationException("CultMesh body publication generation values must be non-negative."); + if (expectedRecordKey.HasValue && !publication.RecordKey.Equals(expectedRecordKey.Value)) + throw new InvalidOperationException("CultMesh body publication record key disagrees with its generation envelope."); ValidateDescriptor(publication, publication.PreferredLocal, "preferred local"); ValidateDescriptor(publication, publication.NetworkFallback, "network fallback"); if (publication.PreferredLocal.TransportKind == CultMeshBodyTransportKind.Network) diff --git a/tests/GameCult.Mesh.Tests/CultMeshBodyPublicationTests.cs b/tests/GameCult.Mesh.Tests/CultMeshBodyPublicationTests.cs index 2f2e2a91..ee7a8cf4 100644 --- a/tests/GameCult.Mesh.Tests/CultMeshBodyPublicationTests.cs +++ b/tests/GameCult.Mesh.Tests/CultMeshBodyPublicationTests.cs @@ -23,12 +23,12 @@ public sealed class CultMeshBodyPublicationTests } [Test] - public void TypedDocument_RoundTripsAndRegistersWithLogicalBodyKey() + public void TypedDocument_RoundTripsAndRegistersWithGenerationKey() { var now = DateTimeOffset.UtcNow; var publication = Publication(new byte[] { 1, 2, 3, 4 }, now); var path = Path.Combine(_root, "publication.cc"); - var handle = new CultMeshBodyPublicationHandle(publication.BodyId); + var handle = Handle(publication); CultMesh.WriteSingleFileDocument(path, handle.RecordKey, publication); var restored = CultMesh.ReadSingleFileDocument(path, handle.RecordKey); @@ -37,7 +37,48 @@ public sealed class CultMeshBodyPublicationTests handle.Validate(restored); restored.Should().BeEquivalentTo(publication); registry.GetByDocumentType(typeof(CultMeshBodyPublicationDocument)).Should().NotBeNull(); - handle.RecordKey.Should().Be(CultMeshBodyPublicationDocument.CreateRecordKey(publication.BodyId)); + handle.RecordKey.Should().Be(CultMeshBodyPublicationDocument.CreateRecordKey( + publication.BodyId, publication.ProducerEpoch, publication.Sequence)); + handle.RecordKey.Should().NotBe(CultMeshBodyPublicationDocument.CreateLatestRecordKey(publication.BodyId)); + } + + [Test] + public async System.Threading.Tasks.Task GenerationRecords_PreserveNWhenNPlusOneIsPublished() + { + var now = DateTimeOffset.UtcNow; + var first = Publication(new byte[] { 1, 2, 3, 4 }, now); + var second = Publication(new byte[] { 5, 6, 7, 8 }, now); + second.Sequence++; + second.PreferredLocal.Sequence++; + second.NetworkFallback.Sequence++; + var cache = new CultCache(); + + await cache.UpsertAsync(first, new CultRecordHandle(first.RecordKey)); + await cache.UpsertAsync(second, new CultRecordHandle(second.RecordKey)); + + var restoredFirst = cache.Get(first.RecordKey); + restoredFirst.Should().NotBeNull(); + Handle(first).Validate(restoredFirst!); + restoredFirst!.Sequence.Should().Be(42); + cache.Get(second.RecordKey)!.Sequence.Should().Be(43); + } + + [Test] + public void GenerationHandle_RejectsLatestOrDifferentGenerationEnvelope() + { + var publication = Publication(new byte[4], DateTimeOffset.UtcNow); + var staleLatestKey = CultMeshBodyPublicationDocument.CreateLatestRecordKey(publication.BodyId); + var next = Publication(new byte[4], DateTimeOffset.UtcNow); + next.Sequence++; + next.PreferredLocal.Sequence++; + next.NetworkFallback.Sequence++; + + Action staleLatest = () => CultMeshBodyPublicationValidator.Validate( + publication, publication.BodyId, publication.ProducerEpoch, publication.Sequence, staleLatestKey); + Action substituted = () => Handle(publication).Validate(next); + + staleLatest.Should().Throw().WithMessage("*record key*"); + substituted.Should().Throw().WithMessage("*sequence*"); } [Test] @@ -160,6 +201,9 @@ public sealed class CultMeshBodyPublicationTests }, authorize)); + private static CultMeshBodyPublicationHandle Handle(CultMeshBodyPublicationDocument publication) => + new(publication.BodyId, publication.ProducerEpoch, publication.Sequence); + private static CultMeshBodyValidationRequest Request( CultMeshBodyPublicationDocument publication, DateTimeOffset now) => new()