Publish CultMesh network body bytes

This commit is contained in:
Meta Vens 2026-07-13 18:14:41 +01:00
commit 7d21bb0e1d
2 changed files with 379 additions and 1 deletions

View file

@ -1,4 +1,10 @@
using System;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using GameCult.Caching;
using GameCult.Networking;
using MessagePack;
@ -8,6 +14,217 @@ namespace GameCult.Mesh
public static class CultMeshBodyPublicationSchemaVersions
{
public const string Publication = "gamecult.mesh.body_publication.v1";
public const string NetworkBody = "gamecult.mesh.network_body.v1";
}
public sealed class CultMeshBodyGeneration
{
public string BodyId { get; set; } = string.Empty;
public string ProducerId { get; set; } = string.Empty;
public string SchemaId { get; set; } = string.Empty;
public int LayoutVersion { get; set; }
public int Capacity { get; set; }
public long ProducerEpoch { get; set; }
public long Sequence { get; set; }
public CultMeshBodySynchronization Synchronization { get; set; } = CultMeshBodySynchronization.ImmutableSequence;
public long LeaseExpiresAtUnixMs { get; set; }
}
[MessagePackObject]
[CultDocument("gamecult.mesh.network_body", CultMeshBodyPublicationSchemaVersions.NetworkBody)]
public sealed class CultMeshNetworkBodyDocument
{
[Key(0), CultName] public string CapabilityToken { get; set; } = string.Empty;
[Key(1), CultIndex] public string BodyId { get; set; } = string.Empty;
[Key(2), CultIndex] public string ProducerId { get; set; } = string.Empty;
[Key(3)] public string SchemaId { get; set; } = string.Empty;
[Key(4)] public int LayoutVersion { get; set; }
[Key(5)] public long ByteSize { get; set; }
[Key(6)] public int Capacity { get; set; }
[Key(7)] public long ProducerEpoch { get; set; }
[Key(8)] public long Sequence { get; set; }
[Key(9)] public CultMeshBodySynchronization Synchronization { get; set; }
[Key(10)] public long LeaseExpiresAtUnixMs { get; set; }
[Key(11)] public string SemanticHash { get; set; } = string.Empty;
[Key(12)] public string ManifestRecordKey { get; set; } = string.Empty;
public static CultRecordKey CreateRecordKey(string capabilityToken)
{
if (string.IsNullOrWhiteSpace(capabilityToken))
throw new ArgumentException("Network body capability token is required.", nameof(capabilityToken));
return new CultRecordKey("mesh:network-body:" + capabilityToken);
}
[IgnoreMember]
public CultRecordKey RecordKey => CreateRecordKey(CapabilityToken);
}
public sealed class CultMeshNetworkBodyPublisher
{
private readonly CultCache _cache;
private readonly Func<CultMeshBodyGeneration, bool> _authorizePublication;
private readonly int _chunkSizeBytes;
public CultMeshNetworkBodyPublisher(
CultCache cache,
Func<CultMeshBodyGeneration, bool> authorizePublication,
int chunkSizeBytes = CultMeshCdnPackOptions.DefaultChunkSizeBytes)
{
_cache = cache ?? throw new ArgumentNullException(nameof(cache));
_authorizePublication = authorizePublication ?? throw new ArgumentNullException(nameof(authorizePublication));
if (chunkSizeBytes <= 0 || chunkSizeBytes > CultMeshCdnPackOptions.DefaultChunkSizeBytes)
throw new ArgumentOutOfRangeException(nameof(chunkSizeBytes), "Network body chunks must be positive and no larger than the CultMesh CDN default bound.");
_chunkSizeBytes = chunkSizeBytes;
}
public async Task<CultMeshBodyDescriptor> PublishAsync(CultMeshBodyGeneration generation, byte[] body)
{
ValidateGeneration(generation);
if (body == null) throw new ArgumentNullException(nameof(body));
if (!_authorizePublication(generation))
throw new UnauthorizedAccessException("CultMesh body producer is not authorized to publish this logical body.");
var semanticHash = CultMeshBodyDescriptorValidator.ComputeSemanticHash(body);
var capabilityToken = CreateCapabilityToken(generation);
var recordKey = CultMeshNetworkBodyDocument.CreateRecordKey(capabilityToken);
var existing = _cache.Get<CultMeshNetworkBodyDocument>(recordKey);
if (existing != null)
{
ValidateImmutableGeneration(existing, generation, body.LongLength, semanticHash);
return CreateDescriptor(existing);
}
var artifact = CultMeshCdn.PackArtifact(
generation.BodyId,
body,
new CultMeshCdnPackOptions
{
ChunkSizeBytes = _chunkSizeBytes,
Kind = CultMeshCdnArtifactKinds.Package,
Version = generation.ProducerEpoch.ToString(CultureInfo.InvariantCulture) + "." + generation.Sequence.ToString(CultureInfo.InvariantCulture)
});
await CultMeshCdn.PublishAsync(_cache, artifact).ConfigureAwait(false);
var document = new CultMeshNetworkBodyDocument
{
CapabilityToken = capabilityToken,
BodyId = generation.BodyId,
ProducerId = generation.ProducerId,
SchemaId = generation.SchemaId,
LayoutVersion = generation.LayoutVersion,
ByteSize = body.LongLength,
Capacity = generation.Capacity,
ProducerEpoch = generation.ProducerEpoch,
Sequence = generation.Sequence,
Synchronization = generation.Synchronization,
LeaseExpiresAtUnixMs = generation.LeaseExpiresAtUnixMs,
SemanticHash = semanticHash,
ManifestRecordKey = artifact.ManifestKey.Value
};
await _cache.UpsertAsync(document, new CultRecordHandle<CultMeshNetworkBodyDocument>(recordKey)).ConfigureAwait(false);
return CreateDescriptor(document);
}
private static void ValidateGeneration(CultMeshBodyGeneration generation)
{
if (generation == null) throw new ArgumentNullException(nameof(generation));
if (string.IsNullOrWhiteSpace(generation.BodyId)) throw new ArgumentException("Body identity is required.", nameof(generation));
if (string.IsNullOrWhiteSpace(generation.ProducerId)) throw new ArgumentException("Producer identity is required.", nameof(generation));
if (string.IsNullOrWhiteSpace(generation.SchemaId)) throw new ArgumentException("Schema identity is required.", nameof(generation));
if (generation.LayoutVersion < 0 || generation.Capacity < 0 || generation.ProducerEpoch < 0 || generation.Sequence < 0)
throw new ArgumentOutOfRangeException(nameof(generation), "Body generation values must be non-negative.");
if (generation.LeaseExpiresAtUnixMs <= 0) throw new ArgumentOutOfRangeException(nameof(generation), "Body generation requires a positive lease expiry.");
}
private static string CreateCapabilityToken(CultMeshBodyGeneration generation)
{
using var stream = new MemoryStream();
using (var writer = new BinaryWriter(stream, Encoding.UTF8, leaveOpen: true))
{
writer.Write(generation.BodyId);
writer.Write(generation.ProducerEpoch);
writer.Write(generation.Sequence);
}
using var sha256 = SHA256.Create();
return string.Concat(sha256.ComputeHash(stream.ToArray()).Select(value => value.ToString("x2", CultureInfo.InvariantCulture)));
}
private static void ValidateImmutableGeneration(
CultMeshNetworkBodyDocument existing,
CultMeshBodyGeneration generation,
long byteSize,
string semanticHash)
{
if (!string.Equals(existing.BodyId, generation.BodyId, StringComparison.Ordinal) ||
!string.Equals(existing.ProducerId, generation.ProducerId, StringComparison.Ordinal) ||
!string.Equals(existing.SchemaId, generation.SchemaId, StringComparison.Ordinal) ||
existing.LayoutVersion != generation.LayoutVersion || existing.ByteSize != byteSize ||
existing.Capacity != generation.Capacity || existing.ProducerEpoch != generation.ProducerEpoch ||
existing.Sequence != generation.Sequence || existing.Synchronization != generation.Synchronization ||
existing.LeaseExpiresAtUnixMs != generation.LeaseExpiresAtUnixMs ||
!string.Equals(existing.SemanticHash, semanticHash, StringComparison.Ordinal))
throw new InvalidOperationException("CultMesh body generation is immutable and was already published with different content or metadata.");
}
private static CultMeshBodyDescriptor CreateDescriptor(CultMeshNetworkBodyDocument document) => new()
{
BodyId = document.BodyId,
SchemaId = document.SchemaId,
LayoutVersion = document.LayoutVersion,
ByteSize = document.ByteSize,
Capacity = document.Capacity,
ProducerEpoch = document.ProducerEpoch,
Sequence = document.Sequence,
AccessMode = CultMeshBodyAccessMode.ReadOnly,
Synchronization = document.Synchronization,
LeaseExpiresAtUnixMs = document.LeaseExpiresAtUnixMs,
TransportKind = CultMeshBodyTransportKind.Network,
CapabilityToken = document.CapabilityToken,
SemanticHash = document.SemanticHash
};
}
public sealed class CultMeshNetworkBodyResolver
{
private readonly CultCache _cache;
public CultMeshNetworkBodyResolver(CultCache cache) =>
_cache = cache ?? throw new ArgumentNullException(nameof(cache));
public Func<CultMeshBodyDescriptor, byte[]> CreateFetchDelegate() => Fetch;
public byte[] Fetch(CultMeshBodyDescriptor descriptor)
{
if (descriptor == null) throw new ArgumentNullException(nameof(descriptor));
if (descriptor.TransportKind != CultMeshBodyTransportKind.Network)
throw new NotSupportedException("CultMesh network body resolver requires a network descriptor.");
var document = _cache.Get<CultMeshNetworkBodyDocument>(
CultMeshNetworkBodyDocument.CreateRecordKey(descriptor.CapabilityToken))
?? throw new FileNotFoundException("CultMesh network body capability is missing.", descriptor.CapabilityToken);
ValidateDescriptor(document, descriptor);
var manifestKey = new CultRecordKey(document.ManifestRecordKey);
var manifest = _cache.Get<CultMeshCdnArtifactManifest>(manifestKey)
?? throw new FileNotFoundException("CultMesh network body manifest is missing.", manifestKey.Value);
if (!string.Equals(CultMeshCdnArtifactManifest.CreateRecordKey(manifest).Value, manifestKey.Value, StringComparison.Ordinal))
throw new InvalidDataException("CultMesh network body manifest identity does not match its capability binding.");
if (manifest.SizeBytes != document.ByteSize ||
!string.Equals(CultMeshCdn.NormalizeHash(manifest.ContentHash, nameof(manifest.ContentHash)), document.SemanticHash, StringComparison.Ordinal))
throw new InvalidDataException("CultMesh network body manifest disagrees with its capability binding.");
return CultMeshCdn.ReadArtifact(_cache, manifest);
}
private static void ValidateDescriptor(CultMeshNetworkBodyDocument document, CultMeshBodyDescriptor descriptor)
{
if (!string.Equals(document.CapabilityToken, descriptor.CapabilityToken, StringComparison.Ordinal) ||
!string.Equals(document.BodyId, descriptor.BodyId, StringComparison.Ordinal) ||
!string.Equals(document.SchemaId, descriptor.SchemaId, StringComparison.Ordinal) ||
document.LayoutVersion != descriptor.LayoutVersion || document.ByteSize != descriptor.ByteSize ||
document.Capacity != descriptor.Capacity || document.ProducerEpoch != descriptor.ProducerEpoch ||
document.Sequence != descriptor.Sequence || document.Synchronization != descriptor.Synchronization ||
document.LeaseExpiresAtUnixMs != descriptor.LeaseExpiresAtUnixMs ||
!string.Equals(document.SemanticHash, descriptor.SemanticHash, StringComparison.Ordinal))
throw new InvalidDataException("CultMesh network body descriptor disagrees with its capability binding.");
}
}
[MessagePackObject]
@ -134,7 +351,10 @@ namespace GameCult.Mesh
{
documents ??= CultDocumentRegistry.Shared;
return new CultNetDocumentRegistry(documents)
.Register(CultNetDocumentBinding.ForDocument<CultMeshBodyPublicationDocument>(documents));
.Register(CultNetDocumentBinding.ForDocument<CultMeshBodyPublicationDocument>(documents))
.Register(CultNetDocumentBinding.ForDocument<CultMeshNetworkBodyDocument>(documents))
.Register(CultNetDocumentBinding.ForDocument<CultMeshCdnArtifactManifest>(documents))
.Register(CultNetDocumentBinding.ForDocument<CultMeshCdnArtifactChunk>(documents));
}
}
}

View file

@ -0,0 +1,158 @@
using System;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using FluentAssertions;
using GameCult.Caching;
using NUnit.Framework;
namespace GameCult.Mesh.Tests;
public sealed class CultMeshNetworkBodyPublicationTests
{
private CultCache _cache = null!;
private string _mappedRoot = null!;
private DateTimeOffset _now;
[SetUp]
public void SetUp()
{
_cache = new CultCache();
_mappedRoot = Path.Combine(Path.GetTempPath(), "cultmesh-network-body-tests", Guid.NewGuid().ToString("N"));
_now = DateTimeOffset.UtcNow;
}
[TearDown]
public void TearDown()
{
_cache.Dispose();
if (Directory.Exists(_mappedRoot)) Directory.Delete(_mappedRoot, true);
}
[Test]
public async Task PublishAndFetch_RoundTripsThroughTypedCdnDocuments()
{
var bytes = Enumerable.Range(0, 41).Select(value => (byte)value).ToArray();
var descriptor = await Publisher(chunkSizeBytes: 8).PublishAsync(Generation(), bytes);
var resolver = new CultMeshNetworkBodyResolver(_cache);
var fetched = resolver.Fetch(descriptor);
descriptor.TransportKind.Should().Be(CultMeshBodyTransportKind.Network);
descriptor.CapabilityToken.Should().NotBeNullOrWhiteSpace();
fetched.Should().Equal(bytes);
_cache.Get<CultMeshNetworkBodyDocument>(CultMeshNetworkBodyDocument.CreateRecordKey(descriptor.CapabilityToken))
.Should().NotBeNull();
}
[Test]
public async Task LocalAndNetworkDescriptors_AreAcceptedAsOneLogicalGeneration()
{
var bytes = BitConverter.GetBytes(42.25f);
var generation = Generation();
var local = new CultMeshMappedBodyPublisher(_mappedRoot, TimeSpan.FromMinutes(1)).Publish(
generation.BodyId, generation.SchemaId, generation.LayoutVersion, generation.Capacity,
generation.ProducerEpoch, generation.Sequence, bytes, _now);
generation.LeaseExpiresAtUnixMs = local.LeaseExpiresAtUnixMs;
var network = await Publisher().PublishAsync(generation, bytes);
var service = new CultMeshBodyTransportService(
new ICultMeshBodyTransportAdapter[]
{
new CultMeshMappedBodyAdapter(_mappedRoot),
new CultMeshNetworkBodyAdapter(new CultMeshNetworkBodyResolver(_cache).CreateFetchDelegate())
},
_ => true);
using var lease = service.NegotiateReadOnly(local, network, Request(network)).Lease;
lease.TransportKind.Should().Be(CultMeshBodyTransportKind.SharedFileMapping);
lease.ReadSingle(0).Should().Be(42.25f);
}
[TestCase(false)]
[TestCase(true)]
public async Task Fetch_RejectsMissingOrCorruptChunk(bool corrupt)
{
var descriptor = await Publisher(chunkSizeBytes: 2).PublishAsync(Generation(), new byte[] { 1, 2, 3, 4 });
var binding = _cache.Get<CultMeshNetworkBodyDocument>(CultMeshNetworkBodyDocument.CreateRecordKey(descriptor.CapabilityToken))!;
var manifest = _cache.Get<CultMeshCdnArtifactManifest>(new CultRecordKey(binding.ManifestRecordKey))!;
var chunkKey = new CultRecordKey(manifest.Chunks[0].RecordKey);
if (corrupt)
{
var chunk = _cache.Get<CultMeshCdnArtifactChunk>(chunkKey)!;
chunk.Payload[0] ^= 0xff;
await _cache.UpsertAsync(chunk, new CultRecordHandle<CultMeshCdnArtifactChunk>(chunkKey));
}
else
{
_cache.Remove(chunkKey);
}
Action fetch = () => new CultMeshNetworkBodyResolver(_cache).Fetch(descriptor);
if (corrupt) fetch.Should().Throw<InvalidDataException>();
else fetch.Should().Throw<FileNotFoundException>();
}
[Test]
public async Task Fetch_RejectsStaleDescriptorGeneration()
{
var descriptor = await Publisher().PublishAsync(Generation(), new byte[] { 1, 2, 3, 4 });
descriptor.Sequence--;
Action fetch = () => new CultMeshNetworkBodyResolver(_cache).Fetch(descriptor);
fetch.Should().Throw<InvalidDataException>().WithMessage("*capability binding*");
}
[Test]
public async Task Publish_RejectsUnauthorizedProducerBeforeWritingDocuments()
{
var generation = Generation();
var publisher = new CultMeshNetworkBodyPublisher(_cache, _ => false);
Func<Task> publish = () => publisher.PublishAsync(generation, new byte[] { 1, 2, 3, 4 });
await publish.Should().ThrowAsync<UnauthorizedAccessException>();
}
[Test]
public async Task Publish_RejectsMutationOfAnExistingGeneration()
{
var publisher = Publisher();
var generation = Generation();
await publisher.PublishAsync(generation, new byte[] { 1, 2, 3, 4 });
Func<Task> republish = () => publisher.PublishAsync(generation, new byte[] { 1, 2, 3, 5 });
await republish.Should().ThrowAsync<InvalidOperationException>().WithMessage("*immutable*");
}
private CultMeshNetworkBodyPublisher Publisher(int chunkSizeBytes = CultMeshCdnPackOptions.DefaultChunkSizeBytes) =>
new(_cache, generation => generation.ProducerId == "aetheria", chunkSizeBytes);
private CultMeshBodyGeneration Generation() => new()
{
BodyId = "aetheria:entities",
ProducerId = "aetheria",
SchemaId = "eve.entity_soa.v1",
LayoutVersion = 2,
Capacity = 128,
ProducerEpoch = 7,
Sequence = 42,
Synchronization = CultMeshBodySynchronization.ImmutableSequence,
LeaseExpiresAtUnixMs = _now.AddMinutes(1).ToUnixTimeMilliseconds()
};
private CultMeshBodyValidationRequest Request(CultMeshBodyDescriptor descriptor) => new()
{
BodyId = descriptor.BodyId,
SchemaId = descriptor.SchemaId,
LayoutVersion = descriptor.LayoutVersion,
ProducerEpoch = descriptor.ProducerEpoch,
Sequence = descriptor.Sequence,
Capacity = descriptor.Capacity,
AccessMode = CultMeshBodyAccessMode.ReadOnly,
NowUtc = _now
};
}