diff --git a/src/GameCult.Mesh/CultMesh.cs b/src/GameCult.Mesh/CultMesh.cs index dab5dd28..460584b6 100644 --- a/src/GameCult.Mesh/CultMesh.cs +++ b/src/GameCult.Mesh/CultMesh.cs @@ -380,6 +380,7 @@ namespace GameCult.Mesh return local; } } + /// /// A locally hosted CultMesh node over CultCache, CultNet transport, and the mesh database facade. /// @@ -680,6 +681,110 @@ namespace GameCult.Mesh return new CultMeshStreamCatalog(); } + /// + /// Packs bytes into content-addressed CDN chunk documents and a versioned artifact manifest. + /// + public static CultMeshCdnArtifact PackCdnArtifact( + string artifactId, + byte[] payload, + CultMeshCdnPackOptions? options = null) + { + return CultMeshCdn.PackArtifact(artifactId, payload, options); + } + + /// + /// Publishes a packed CDN artifact into a local cache. + /// + public static Task PublishCdnArtifactAsync( + CultCache cache, + CultMeshCdnArtifact artifact) + { + return CultMeshCdn.PublishAsync(cache, artifact); + } + + /// + /// Publishes a packed CDN artifact into a distributed CultNet database. + /// + public static Task PublishCdnArtifactAsync( + CultNetDatabase database, + CultMeshCdnArtifact artifact) + { + return CultMeshCdn.PublishAsync(database, artifact); + } + + /// + /// Reassembles and verifies a CDN artifact from a local cache. + /// + public static byte[] ReadCdnArtifact( + CultCache cache, + CultMeshCdnArtifactManifest manifest) + { + return CultMeshCdn.ReadArtifact(cache, manifest); + } + + /// + /// Reassembles and verifies a CDN artifact from a distributed CultNet database. + /// + public static Task ReadCdnArtifactAsync( + CultNetDatabase database, + CultMeshCdnArtifactManifest manifest) + { + return CultMeshCdn.ReadArtifactAsync(database, manifest); + } + + /// + /// Creates a CultNet document registry for CDN artifact manifests and chunks. + /// + public static CultNetDocumentRegistry CreateCdnDocumentRegistry(CultDocumentRegistry? documents = null) + { + return CultMeshCdn.CreateDocumentRegistry(documents); + } + + /// + /// Computes and stamps the content hash for a portable entity prefab package. + /// + public static CultMeshEntityPrefabPackage FinalizeEntityPrefabPackage( + CultMeshEntityPrefabPackage package) + { + return CultMeshEntityPrefabs.FinalizePackage(package); + } + + /// + /// Publishes a portable entity prefab package into a local cache. + /// + public static Task PublishEntityPrefabPackageAsync( + CultCache cache, + CultMeshEntityPrefabPackage package) + { + return CultMeshEntityPrefabs.PublishAsync(cache, package); + } + + /// + /// Publishes a portable entity prefab package into a distributed CultNet database. + /// + public static Task PublishEntityPrefabPackageAsync( + CultNetDatabase database, + CultMeshEntityPrefabPackage package) + { + return CultMeshEntityPrefabs.PublishAsync(database, package); + } + + /// + /// Creates a CultNet document registry for portable entity prefab packages. + /// + public static CultNetDocumentRegistry CreateEntityPrefabDocumentRegistry(CultDocumentRegistry? documents = null) + { + return CultMeshEntityPrefabs.CreateDocumentRegistry(documents); + } + + /// + /// Creates a CultNet document registry for CDN assets and portable entity prefab packages. + /// + public static CultNetDocumentRegistry CreateAssetPipelineDocumentRegistry(CultDocumentRegistry? documents = null) + { + return CultMeshEntityPrefabs.CreateAssetPipelineDocumentRegistry(documents); + } + /// /// Creates a managed Verse context for generated domain sugar. /// @@ -1700,6 +1805,7 @@ namespace GameCult.Mesh if (verse == null) throw new ArgumentNullException(nameof(verse)); return DocumentsFromPublication(source, bindings, verse.Context, storeOptions, peerOptions); } + /// /// Reads configured publication documents, hydrates them into a local node, and returns local handles as a catalog. /// @@ -1751,6 +1857,7 @@ namespace GameCult.Mesh peerOptions, flush); } + /// /// Reads one typed document from a configured publication source and hydrates it into a local node. /// @@ -1834,6 +1941,7 @@ namespace GameCult.Mesh peerOptions, flush); } + internal static CultMeshStoreDocumentOptions WithPublicationBindingOptions( CultMeshStoreDocumentOptions? options, CultRecordKey key, @@ -1881,6 +1989,7 @@ namespace GameCult.Mesh RudpResendDelayMs = options?.RudpResendDelayMs ?? 25 }; } + /// /// Creates a typed document handle directly over one distributed CultNet database record. /// diff --git a/src/GameCult.Mesh/CultMeshCdn.cs b/src/GameCult.Mesh/CultMeshCdn.cs new file mode 100644 index 00000000..72f38c6a --- /dev/null +++ b/src/GameCult.Mesh/CultMeshCdn.cs @@ -0,0 +1,578 @@ +using System; +using System.Collections.Generic; +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; + +namespace GameCult.Mesh +{ + /// + /// Schema versions for CultMesh distributed CDN documents. + /// + public static class CultMeshCdnSchemaVersions + { + /// Manifest document schema id. + public const string ArtifactManifest = "gamecult.mesh.cdn_artifact_manifest.v1"; + /// Chunk document schema id. + public const string ArtifactChunk = "gamecult.mesh.cdn_artifact_chunk.v1"; + } + + /// + /// Well-known CultMesh CDN artifact kinds. + /// + public static class CultMeshCdnArtifactKinds + { + /// Game, UI, shader, texture, audio, or data asset payload. + public const string Asset = "asset"; + /// Executable build or install/update payload. + public const string Build = "build"; + /// Generic packaged payload. + public const string Package = "package"; + } + + /// + /// Options for packing bytes into CultMesh CDN documents. + /// + public sealed class CultMeshCdnPackOptions + { + /// Default CDN chunk size. + public const int DefaultChunkSizeBytes = 256 * 1024; + + /// Maximum bytes per content chunk. + public int ChunkSizeBytes { get; set; } = DefaultChunkSizeBytes; + + /// Artifact kind, such as asset or build. + public string Kind { get; set; } = CultMeshCdnArtifactKinds.Asset; + + /// Caller-defined artifact version. + public string Version { get; set; } = string.Empty; + + /// Artifact MIME type. + public string MimeType { get; set; } = "application/octet-stream"; + + /// Search and routing tags copied to the manifest. + public string[] Tags { get; set; } = Array.Empty(); + + /// Caller metadata copied to the manifest. + public Dictionary Metadata { get; set; } = new(); + + /// Override manifest creation timestamp in round-trip UTC format. + public string? CreatedAtUtc { get; set; } + } + + /// + /// Reference from an artifact manifest to one content-addressed chunk document. + /// + [MessagePackObject] + public sealed class CultMeshCdnChunkRef + { + /// SHA-256 hash of the referenced chunk payload. + [Key(0)] + public string ChunkHash { get; set; } = string.Empty; + + /// Byte offset of this chunk inside the materialized artifact. + [Key(1)] + public long Offset { get; set; } + + /// Number of payload bytes contributed by this chunk. + [Key(2)] + public int SizeBytes { get; set; } + + /// CultCache record key for the referenced chunk document. + [Key(3)] + public string RecordKey { get; set; } = string.Empty; + } + + /// + /// Content-addressed artifact chunk stored in CultCache and replicated through CultNet. + /// + [MessagePackObject] + [CultDocument("gamecult.mesh.cdn_artifact_chunk", CultMeshCdnSchemaVersions.ArtifactChunk)] + public sealed class CultMeshCdnArtifactChunk + { + /// SHA-256 hash of the chunk payload. + [Key(0)] + [CultName] + public string ChunkHash { get; set; } = string.Empty; + + /// Payload byte count. + [Key(1)] + public int SizeBytes { get; set; } + + /// Raw chunk payload bytes. + [Key(2)] + public byte[] Payload { get; set; } = Array.Empty(); + + /// Builds the deterministic content-addressed chunk record key. + public static CultRecordKey CreateRecordKey(CultMeshCdnArtifactChunk chunk) + { + if (chunk == null) throw new ArgumentNullException(nameof(chunk)); + return CreateRecordKey(chunk.ChunkHash); + } + + /// Builds the deterministic content-addressed chunk record key. + public static CultRecordKey CreateRecordKey(string chunkHash) + { + return new CultRecordKey("mesh:cdn:chunk:" + CultMeshCdn.NormalizeHash(chunkHash, nameof(chunkHash))); + } + } + + /// + /// Manifest for one versioned CDN artifact assembled from content-addressed chunks. + /// + [MessagePackObject] + [CultDocument("gamecult.mesh.cdn_artifact_manifest", CultMeshCdnSchemaVersions.ArtifactManifest)] + public sealed class CultMeshCdnArtifactManifest + { + /// Stable artifact id, such as a logical asset or build path. + [Key(0)] + [CultName] + public string ArtifactId { get; set; } = string.Empty; + + /// Artifact kind, such as asset, build, or package. + [Key(1)] + [CultIndex] + public string Kind { get; set; } = CultMeshCdnArtifactKinds.Asset; + + /// Caller-defined artifact version. + [Key(2)] + [CultIndex] + public string Version { get; set; } = string.Empty; + + /// SHA-256 hash of the full materialized artifact. + [Key(3)] + [CultIndex] + public string ContentHash { get; set; } = string.Empty; + + /// Full materialized artifact size. + [Key(4)] + public long SizeBytes { get; set; } + + /// Artifact MIME type. + [Key(5)] + public string MimeType { get; set; } = "application/octet-stream"; + + /// Manifest creation timestamp in round-trip UTC format. + [Key(6)] + public string CreatedAtUtc { get; set; } = string.Empty; + + /// Ordered chunk references needed to materialize the artifact. + [Key(7)] + public CultMeshCdnChunkRef[] Chunks { get; set; } = Array.Empty(); + + /// Search and routing tags. + [Key(8)] + public string[] Tags { get; set; } = Array.Empty(); + + /// Caller metadata, such as platform or texture channel layout. + [Key(9)] + public Dictionary Metadata { get; set; } = new(); + + /// Builds the deterministic versioned artifact manifest record key. + public static CultRecordKey CreateRecordKey(CultMeshCdnArtifactManifest manifest) + { + if (manifest == null) throw new ArgumentNullException(nameof(manifest)); + return CreateRecordKey(manifest.ArtifactId, manifest.Version, manifest.ContentHash); + } + + /// Builds the deterministic versioned artifact manifest record key. + public static CultRecordKey CreateRecordKey(string artifactId, string version, string contentHash) + { + var artifactToken = CultMeshCdn.StableToken(artifactId, nameof(artifactId)); + var versionToken = string.IsNullOrWhiteSpace(version) + ? "unversioned" + : CultMeshCdn.StableToken(version, nameof(version)); + return new CultRecordKey( + "mesh:cdn:artifact:" + artifactToken + ":" + versionToken + ":" + CultMeshCdn.NormalizeHash(contentHash, nameof(contentHash))); + } + } + + /// + /// Packed CDN artifact ready to publish into a cache or database. + /// + public sealed class CultMeshCdnArtifact + { + /// Creates a packed artifact container. + public CultMeshCdnArtifact( + CultMeshCdnArtifactManifest manifest, + IReadOnlyList chunks) + { + Manifest = manifest ?? throw new ArgumentNullException(nameof(manifest)); + Chunks = chunks ?? throw new ArgumentNullException(nameof(chunks)); + } + + /// Artifact manifest document. + public CultMeshCdnArtifactManifest Manifest { get; } + + /// Content-addressed chunk documents. + public IReadOnlyList Chunks { get; } + + /// Deterministic manifest record key. + public CultRecordKey ManifestKey => CultMeshCdnArtifactManifest.CreateRecordKey(Manifest); + + /// All unique record keys required to replicate this artifact. + public IReadOnlyList RecordKeys => + new[] { ManifestKey }.Concat(Chunks.Select(CultMeshCdnArtifactChunk.CreateRecordKey)).Distinct().ToArray(); + } + + /// + /// Content-addressed byte artifact helpers for distributing assets and builds through CultMesh clients. + /// + public static class CultMeshCdn + { + /// + /// Splits a payload into content-addressed chunk documents and a versioned manifest. + /// + public static CultMeshCdnArtifact PackArtifact( + string artifactId, + byte[] payload, + CultMeshCdnPackOptions? options = null) + { + if (string.IsNullOrWhiteSpace(artifactId)) + { + throw new ArgumentException("Artifact id must be non-empty.", nameof(artifactId)); + } + + if (payload == null) throw new ArgumentNullException(nameof(payload)); + options ??= new CultMeshCdnPackOptions(); + if (options.ChunkSizeBytes <= 0) + { + throw new ArgumentOutOfRangeException(nameof(options), "ChunkSizeBytes must be greater than zero."); + } + + var chunks = new List(); + var refs = new List(); + for (var offset = 0; offset < payload.Length; offset += options.ChunkSizeBytes) + { + var count = Math.Min(options.ChunkSizeBytes, payload.Length - offset); + var chunkPayload = new byte[count]; + Buffer.BlockCopy(payload, offset, chunkPayload, 0, count); + var chunkHash = HashBytes(chunkPayload); + var chunk = new CultMeshCdnArtifactChunk + { + ChunkHash = chunkHash, + SizeBytes = count, + Payload = chunkPayload + }; + chunks.Add(chunk); + refs.Add(new CultMeshCdnChunkRef + { + ChunkHash = chunkHash, + Offset = offset, + SizeBytes = count, + RecordKey = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value + }); + } + + if (payload.Length == 0) + { + var chunkHash = HashBytes(Array.Empty()); + var chunk = new CultMeshCdnArtifactChunk + { + ChunkHash = chunkHash, + SizeBytes = 0, + Payload = Array.Empty() + }; + chunks.Add(chunk); + refs.Add(new CultMeshCdnChunkRef + { + ChunkHash = chunkHash, + Offset = 0, + SizeBytes = 0, + RecordKey = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value + }); + } + + var manifest = new CultMeshCdnArtifactManifest + { + ArtifactId = artifactId, + Kind = string.IsNullOrWhiteSpace(options.Kind) ? CultMeshCdnArtifactKinds.Asset : options.Kind, + Version = options.Version ?? string.Empty, + ContentHash = HashBytes(payload), + SizeBytes = payload.LongLength, + MimeType = string.IsNullOrWhiteSpace(options.MimeType) ? "application/octet-stream" : options.MimeType, + CreatedAtUtc = options.CreatedAtUtc ?? DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture), + Chunks = refs.ToArray(), + Tags = options.Tags ?? Array.Empty(), + Metadata = options.Metadata ?? new Dictionary() + }; + + return new CultMeshCdnArtifact(manifest, chunks); + } + + /// + /// Publishes all chunk documents and the manifest into a local CultCache. + /// + public static async Task PublishAsync( + CultCache cache, + CultMeshCdnArtifact artifact) + { + if (cache == null) throw new ArgumentNullException(nameof(cache)); + if (artifact == null) throw new ArgumentNullException(nameof(artifact)); + + ValidateArtifact(artifact); + foreach (var chunk in artifact.Chunks) + { + await cache.UpsertAsync( + chunk, + new CultRecordHandle( + CultMeshCdnArtifactChunk.CreateRecordKey(chunk))).ConfigureAwait(false); + } + + await cache.UpsertAsync( + artifact.Manifest, + new CultRecordHandle( + CultMeshCdnArtifactManifest.CreateRecordKey(artifact.Manifest))).ConfigureAwait(false); + + return artifact.Manifest; + } + + /// + /// Publishes all chunk documents and the manifest into a distributed CultNet database. + /// + public static async Task PublishAsync( + CultNetDatabase database, + CultMeshCdnArtifact artifact) + { + if (database == null) throw new ArgumentNullException(nameof(database)); + if (artifact == null) throw new ArgumentNullException(nameof(artifact)); + + ValidateArtifact(artifact); + foreach (var chunk in artifact.Chunks) + { + await database.PutAsync(CultMeshCdnArtifactChunk.CreateRecordKey(chunk), chunk) + .ConfigureAwait(false); + } + + await database.PutAsync(CultMeshCdnArtifactManifest.CreateRecordKey(artifact.Manifest), artifact.Manifest) + .ConfigureAwait(false); + return artifact.Manifest; + } + + /// + /// Reassembles and verifies an artifact from a local CultCache. + /// + public static byte[] ReadArtifact(CultCache cache, CultMeshCdnArtifactManifest manifest) + { + if (cache == null) throw new ArgumentNullException(nameof(cache)); + if (manifest == null) throw new ArgumentNullException(nameof(manifest)); + + ValidateManifestShape(manifest); + var output = new byte[checked((int)manifest.SizeBytes)]; + foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset)) + { + var recordKey = string.IsNullOrWhiteSpace(reference.RecordKey) + ? CultMeshCdnArtifactChunk.CreateRecordKey(reference.ChunkHash) + : new CultRecordKey(reference.RecordKey); + var chunk = cache.Get(recordKey) + ?? throw new FileNotFoundException("CDN artifact chunk is missing from the cache.", recordKey.Value); + ValidateChunk(reference, chunk); + Buffer.BlockCopy(chunk.Payload, 0, output, checked((int)reference.Offset), reference.SizeBytes); + } + + var actualHash = HashBytes(output); + if (!string.Equals(NormalizeHash(manifest.ContentHash, nameof(manifest.ContentHash)), actualHash, StringComparison.Ordinal)) + { + throw new InvalidDataException("CDN artifact content hash does not match its manifest."); + } + + return output; + } + + /// + /// Reassembles and verifies an artifact from a distributed CultNet database. + /// + public static async Task ReadArtifactAsync( + CultNetDatabase database, + CultMeshCdnArtifactManifest manifest) + { + if (database == null) throw new ArgumentNullException(nameof(database)); + if (manifest == null) throw new ArgumentNullException(nameof(manifest)); + + ValidateManifestShape(manifest); + var output = new byte[checked((int)manifest.SizeBytes)]; + foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset)) + { + var recordKey = string.IsNullOrWhiteSpace(reference.RecordKey) + ? CultMeshCdnArtifactChunk.CreateRecordKey(reference.ChunkHash) + : new CultRecordKey(reference.RecordKey); + var chunk = await database.GetAsync(recordKey).ConfigureAwait(false) + ?? throw new FileNotFoundException("CDN artifact chunk is missing from the database.", recordKey.Value); + ValidateChunk(reference, chunk); + Buffer.BlockCopy(chunk.Payload, 0, output, checked((int)reference.Offset), reference.SizeBytes); + } + + var actualHash = HashBytes(output); + if (!string.Equals(NormalizeHash(manifest.ContentHash, nameof(manifest.ContentHash)), actualHash, StringComparison.Ordinal)) + { + throw new InvalidDataException("CDN artifact content hash does not match its manifest."); + } + + return output; + } + + /// + /// Creates a raw CultNet document registry for CDN manifests and chunks. + /// + public static CultNetDocumentRegistry CreateDocumentRegistry(CultDocumentRegistry? documents = null) + { + documents ??= CultDocumentRegistry.Shared; + return new CultNetDocumentRegistry(documents) + .Register(CultNetDocumentBinding.ForDocument(documents)) + .Register(CultNetDocumentBinding.ForDocument(documents)); + } + + internal static string HashBytes(byte[] bytes) + { + using var sha256 = SHA256.Create(); + var hash = sha256.ComputeHash(bytes); + var builder = new StringBuilder(hash.Length * 2); + foreach (var value in hash) + { + builder.Append(value.ToString("x2", CultureInfo.InvariantCulture)); + } + + return builder.ToString(); + } + + private static void ValidateArtifact(CultMeshCdnArtifact artifact) + { + ValidateManifestShape(artifact.Manifest); + var expectedRefs = artifact.Chunks + .Select(chunk => new + { + Hash = HashBytes(chunk.Payload), + ChunkHash = NormalizeHash(chunk.ChunkHash, nameof(chunk.ChunkHash)), + chunk.SizeBytes, + Key = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value + }) + .ToArray(); + + if (artifact.Manifest.Chunks.Length != expectedRefs.Length) + { + throw new InvalidDataException("CDN artifact manifest chunk count does not match chunk payloads."); + } + + for (var i = 0; i < expectedRefs.Length; i++) + { + var reference = artifact.Manifest.Chunks[i]; + var expected = expectedRefs[i]; + if (!string.Equals(NormalizeHash(reference.ChunkHash, nameof(reference.ChunkHash)), expected.Hash, StringComparison.Ordinal) || + !string.Equals(expected.ChunkHash, expected.Hash, StringComparison.Ordinal) || + reference.SizeBytes != expected.SizeBytes || + !string.Equals(reference.RecordKey, expected.Key, StringComparison.Ordinal)) + { + throw new InvalidDataException("CDN artifact manifest chunk reference does not match its chunk payload."); + } + } + + var materialized = new byte[checked((int)artifact.Manifest.SizeBytes)]; + foreach (var reference in artifact.Manifest.Chunks.OrderBy(chunk => chunk.Offset)) + { + var chunk = artifact.Chunks.First(candidate => + string.Equals( + CultMeshCdnArtifactChunk.CreateRecordKey(candidate).Value, + reference.RecordKey, + StringComparison.Ordinal)); + Buffer.BlockCopy(chunk.Payload, 0, materialized, checked((int)reference.Offset), reference.SizeBytes); + } + + if (!string.Equals( + NormalizeHash(artifact.Manifest.ContentHash, nameof(artifact.Manifest.ContentHash)), + HashBytes(materialized), + StringComparison.Ordinal)) + { + throw new InvalidDataException("CDN artifact content hash does not match its manifest."); + } + } + + private static void ValidateManifestShape(CultMeshCdnArtifactManifest manifest) + { + if (manifest.SizeBytes < 0) + { + throw new InvalidDataException("CDN artifact manifest has a negative size."); + } + + if (manifest.SizeBytes > int.MaxValue) + { + throw new InvalidDataException("CDN artifact is too large to materialize into one byte array."); + } + + var expectedOffset = 0L; + foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset)) + { + if (reference.Offset != expectedOffset) + { + throw new InvalidDataException("CDN artifact chunks are not contiguous."); + } + + if (reference.SizeBytes < 0) + { + throw new InvalidDataException("CDN artifact chunk has a negative size."); + } + + expectedOffset += reference.SizeBytes; + } + + if (expectedOffset != manifest.SizeBytes) + { + throw new InvalidDataException("CDN artifact chunk sizes do not sum to the manifest size."); + } + } + + private static void ValidateChunk(CultMeshCdnChunkRef reference, CultMeshCdnArtifactChunk chunk) + { + if (chunk.Payload.Length != reference.SizeBytes || + chunk.SizeBytes != reference.SizeBytes) + { + throw new InvalidDataException("CDN artifact chunk payload metadata does not match its manifest reference."); + } + + var actualHash = HashBytes(chunk.Payload); + if (!string.Equals(NormalizeHash(reference.ChunkHash, nameof(reference.ChunkHash)), actualHash, StringComparison.Ordinal) || + !string.Equals(NormalizeHash(chunk.ChunkHash, nameof(chunk.ChunkHash)), actualHash, StringComparison.Ordinal)) + { + throw new InvalidDataException("CDN artifact chunk hash does not match its payload."); + } + } + + internal static string NormalizeHash(string hash, string parameterName) + { + if (string.IsNullOrWhiteSpace(hash)) + { + throw new ArgumentException("Hash must be non-empty.", parameterName); + } + + var value = hash.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase) + ? hash.Substring("sha256:".Length) + : hash; + return value.Trim().ToLowerInvariant(); + } + + internal static string StableToken(string value, string parameterName) + { + if (string.IsNullOrWhiteSpace(value)) + { + throw new ArgumentException("Value must be non-empty.", parameterName); + } + + var normalized = value.Trim().ToLowerInvariant(); + var builder = new StringBuilder(normalized.Length); + foreach (var c in normalized) + { + builder.Append(char.IsLetterOrDigit(c) || c == '-' || c == '_' || c == '.' ? c : '-'); + } + + var token = builder.ToString().Trim('-'); + return string.IsNullOrWhiteSpace(token) + ? HashBytes(Encoding.UTF8.GetBytes(value)) + : token; + } + } +} diff --git a/src/GameCult.Mesh/CultMeshEntityPrefabs.cs b/src/GameCult.Mesh/CultMeshEntityPrefabs.cs new file mode 100644 index 00000000..194c9360 --- /dev/null +++ b/src/GameCult.Mesh/CultMeshEntityPrefabs.cs @@ -0,0 +1,395 @@ +using System; +using System.Collections.Generic; +using System.Globalization; +using System.Linq; +using System.Text; +using System.Threading.Tasks; +using GameCult.Caching; +using GameCult.Networking; +using MessagePack; + +namespace GameCult.Mesh +{ + /// + /// Schema versions for portable entity prefab packages. + /// + public static class CultMeshEntityPrefabSchemaVersions + { + /// Portable prefab package schema id. + public const string Package = "gamecult.mesh.entity_prefab_package.v1"; + } + + /// + /// Well-known portable prefab node kinds. + /// + public static class CultMeshEntityPrefabNodeKinds + { + /// Transform-only node. + public const string Empty = "empty"; + /// Renderable mesh node. + public const string Mesh = "mesh"; + /// Collider node. + public const string Collider = "collider"; + /// Particle or projectile effect node. + public const string Effect = "effect"; + /// Camera or view anchor node. + public const string Camera = "camera"; + /// Runtime attachment point. + public const string Socket = "socket"; + } + + /// + /// Well-known prefab asset roles. + /// + public static class CultMeshEntityPrefabAssetRoles + { + /// Mesh geometry payload. + public const string Mesh = "mesh"; + /// Texture image payload. + public const string Texture = "texture"; + /// Material definition payload. + public const string Material = "material"; + /// Animation clip payload. + public const string Animation = "animation"; + /// Audio payload. + public const string Audio = "audio"; + } + + /// + /// Portable transform using Blender/CultMesh source coordinates before runtime lowering. + /// + [MessagePackObject] + public sealed class CultMeshEntityPrefabTransform + { + /// Local position vector. + [Key(0)] + public float[] Position { get; set; } = [0f, 0f, 0f]; + + /// Local rotation quaternion. + [Key(1)] + public float[] Rotation { get; set; } = [0f, 0f, 0f, 1f]; + + /// Local scale vector. + [Key(2)] + public float[] Scale { get; set; } = [1f, 1f, 1f]; + } + + /// + /// Runtime component intent attached to a portable prefab node. + /// + [MessagePackObject] + public sealed class CultMeshEntityPrefabComponent + { + /// Portable component kind or runtime adapter type. + [Key(0)] + public string Type { get; set; } = string.Empty; + + /// String-valued component properties for runtime-specific lowering. + [Key(1)] + public Dictionary Properties { get; set; } = new(); + } + + /// + /// Reference from a prefab package to a CDN artifact manifest. + /// + [MessagePackObject] + public sealed class CultMeshEntityPrefabAssetRef + { + /// Stable source asset id inside the prefab package. + [Key(0)] + public string AssetId { get; set; } = string.Empty; + + /// Semantic role, such as mesh, texture, material, or animation. + [Key(1)] + public string Role { get; set; } = string.Empty; + + /// CultCache record key for the referenced CDN artifact manifest. + [Key(2)] + public string CdnManifestRecordKey { get; set; } = string.Empty; + + /// Full artifact content hash copied from the referenced CDN manifest. + [Key(3)] + public string ContentHash { get; set; } = string.Empty; + + /// Artifact MIME type copied from the referenced CDN manifest. + [Key(4)] + public string MimeType { get; set; } = string.Empty; + + /// Runtime and source metadata for the asset reference. + [Key(5)] + public Dictionary Metadata { get; set; } = new(); + } + + /// + /// One node in a portable entity prefab graph. + /// + [MessagePackObject] + public sealed class CultMeshEntityPrefabNode + { + /// Stable node id inside the package. + [Key(0)] + public string NodeId { get; set; } = string.Empty; + + /// Source object name. + [Key(1)] + public string Name { get; set; } = string.Empty; + + /// Optional parent node id. + [Key(2)] + public string ParentNodeId { get; set; } = string.Empty; + + /// Node kind. + [Key(3)] + public string Kind { get; set; } = CultMeshEntityPrefabNodeKinds.Empty; + + /// Local transform. + [Key(4)] + public CultMeshEntityPrefabTransform Transform { get; set; } = new(); + + /// Optional mesh asset id used by this node. + [Key(5)] + public string MeshAssetId { get; set; } = string.Empty; + + /// Material asset ids used by this node. + [Key(6)] + public string[] MaterialAssetIds { get; set; } = Array.Empty(); + + /// Runtime component intents attached to this node. + [Key(7)] + public CultMeshEntityPrefabComponent[] Components { get; set; } = Array.Empty(); + + /// Runtime tags copied from source metadata. + [Key(8)] + public string[] Tags { get; set; } = Array.Empty(); + + /// Additional source metadata. + [Key(9)] + public Dictionary Metadata { get; set; } = new(); + } + + /// + /// Portable entity prefab package authored from a Blender collection and lowerable into multiple runtimes. + /// + [MessagePackObject] + [CultDocument("gamecult.mesh.entity_prefab_package", CultMeshEntityPrefabSchemaVersions.Package)] + public sealed class CultMeshEntityPrefabPackage + { + /// Stable logical prefab id. + [Key(0)] + [CultName] + public string PrefabId { get; set; } = string.Empty; + + /// Caller-defined package version. + [Key(1)] + [CultIndex] + public string Version { get; set; } = string.Empty; + + /// Tool that authored the package, such as Brokkr Blender. + [Key(2)] + [CultIndex] + public string SourceTool { get; set; } = string.Empty; + + /// Source scene name or path. + [Key(3)] + public string SourceScene { get; set; } = string.Empty; + + /// Source Blender collection name. + [Key(4)] + [CultIndex] + public string SourceCollection { get; set; } = string.Empty; + + /// Stable hash of graph structure and referenced assets. + [Key(5)] + [CultIndex] + public string ContentHash { get; set; } = string.Empty; + + /// Package creation timestamp in round-trip UTC format. + [Key(6)] + public string CreatedAtUtc { get; set; } = string.Empty; + + /// Referenced CDN assets. + [Key(7)] + public CultMeshEntityPrefabAssetRef[] Assets { get; set; } = Array.Empty(); + + /// Prefab hierarchy nodes. + [Key(8)] + public CultMeshEntityPrefabNode[] Nodes { get; set; } = Array.Empty(); + + /// Search and routing tags. + [Key(9)] + public string[] Tags { get; set; } = Array.Empty(); + + /// Package-level metadata. + [Key(10)] + public Dictionary Metadata { get; set; } = new(); + + /// Builds the deterministic package record key. + public static CultRecordKey CreateRecordKey(CultMeshEntityPrefabPackage package) + { + if (package == null) throw new ArgumentNullException(nameof(package)); + return CreateRecordKey(package.PrefabId, package.Version, package.ContentHash); + } + + /// Builds the deterministic package record key. + public static CultRecordKey CreateRecordKey(string prefabId, string version, string contentHash) + { + var prefabToken = CultMeshCdn.StableToken(prefabId, nameof(prefabId)); + var versionToken = string.IsNullOrWhiteSpace(version) + ? "unversioned" + : CultMeshCdn.StableToken(version, nameof(version)); + return new CultRecordKey( + "mesh:entity-prefab:" + prefabToken + ":" + versionToken + ":" + CultMeshCdn.NormalizeHash(contentHash, nameof(contentHash))); + } + } + + /// + /// Helpers for publishing and validating portable entity prefab packages. + /// + public static class CultMeshEntityPrefabs + { + /// + /// Computes a stable package content hash from graph structure and referenced asset hashes. + /// + public static string ComputeContentHash(CultMeshEntityPrefabPackage package) + { + if (package == null) throw new ArgumentNullException(nameof(package)); + var builder = new StringBuilder(); + builder.Append(package.PrefabId).Append('\u001F') + .Append(package.Version).Append('\u001F') + .Append(package.SourceTool).Append('\u001F') + .Append(package.SourceScene).Append('\u001F') + .Append(package.SourceCollection).Append('\u001F'); + + foreach (var asset in package.Assets.OrderBy(asset => asset.AssetId, StringComparer.Ordinal)) + { + builder.Append("asset").Append('\u001E') + .Append(asset.AssetId).Append('\u001E') + .Append(asset.Role).Append('\u001E') + .Append(asset.CdnManifestRecordKey).Append('\u001E') + .Append(CultMeshCdn.NormalizeHash(asset.ContentHash, nameof(asset.ContentHash))).Append('\u001E') + .Append(asset.MimeType).Append('\u001E') + .Append(StableMap(asset.Metadata)).Append('\u001F'); + } + + foreach (var node in package.Nodes.OrderBy(node => node.NodeId, StringComparer.Ordinal)) + { + builder.Append("node").Append('\u001E') + .Append(node.NodeId).Append('\u001E') + .Append(node.Name).Append('\u001E') + .Append(node.ParentNodeId).Append('\u001E') + .Append(node.Kind).Append('\u001E') + .Append(StableFloats(node.Transform.Position)).Append('\u001E') + .Append(StableFloats(node.Transform.Rotation)).Append('\u001E') + .Append(StableFloats(node.Transform.Scale)).Append('\u001E') + .Append(node.MeshAssetId).Append('\u001E') + .Append(string.Join(",", node.MaterialAssetIds.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001E') + .Append(StableComponents(node.Components)).Append('\u001E') + .Append(string.Join(",", node.Tags.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001E') + .Append(StableMap(node.Metadata)).Append('\u001F'); + } + + builder.Append(string.Join(",", package.Tags.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001F') + .Append(StableMap(package.Metadata)); + + return CultMeshCdn.HashBytes(Encoding.UTF8.GetBytes(builder.ToString())); + } + + /// + /// Stamps the current content hash and creation timestamp on a package. + /// + public static CultMeshEntityPrefabPackage FinalizePackage(CultMeshEntityPrefabPackage package) + { + if (package == null) throw new ArgumentNullException(nameof(package)); + package.CreatedAtUtc = string.IsNullOrWhiteSpace(package.CreatedAtUtc) + ? DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture) + : package.CreatedAtUtc; + package.ContentHash = ComputeContentHash(package); + return package; + } + + /// + /// Publishes a finalized portable entity prefab package into a local cache. + /// + public static async Task PublishAsync( + CultCache cache, + CultMeshEntityPrefabPackage package) + { + if (cache == null) throw new ArgumentNullException(nameof(cache)); + if (package == null) throw new ArgumentNullException(nameof(package)); + ValidatePackage(package); + await cache.UpsertAsync( + package, + new CultRecordHandle( + CultMeshEntityPrefabPackage.CreateRecordKey(package))).ConfigureAwait(false); + return package; + } + + /// + /// Publishes a finalized portable entity prefab package into a distributed CultNet database. + /// + public static async Task PublishAsync( + CultNetDatabase database, + CultMeshEntityPrefabPackage package) + { + if (database == null) throw new ArgumentNullException(nameof(database)); + if (package == null) throw new ArgumentNullException(nameof(package)); + ValidatePackage(package); + await database.PutAsync(CultMeshEntityPrefabPackage.CreateRecordKey(package), package) + .ConfigureAwait(false); + return package; + } + + /// + /// Creates a raw CultNet document registry for entity prefab packages. + /// + public static CultNetDocumentRegistry CreateDocumentRegistry(CultDocumentRegistry? documents = null) + { + documents ??= CultDocumentRegistry.Shared; + return new CultNetDocumentRegistry(documents) + .Register(CultNetDocumentBinding.ForDocument(documents)); + } + + /// + /// Creates a raw CultNet document registry for CDN assets and portable entity prefab packages. + /// + public static CultNetDocumentRegistry CreateAssetPipelineDocumentRegistry(CultDocumentRegistry? documents = null) + { + documents ??= CultDocumentRegistry.Shared; + return CultMeshCdn.CreateDocumentRegistry(documents) + .Register(CultNetDocumentBinding.ForDocument(documents)); + } + + private static void ValidatePackage(CultMeshEntityPrefabPackage package) + { + if (string.IsNullOrWhiteSpace(package.PrefabId)) + { + throw new ArgumentException("Prefab id must be non-empty.", nameof(package)); + } + + var expectedHash = ComputeContentHash(package); + if (!string.Equals(CultMeshCdn.NormalizeHash(package.ContentHash, nameof(package.ContentHash)), expectedHash, StringComparison.Ordinal)) + { + throw new InvalidOperationException("Entity prefab package content hash does not match its graph."); + } + } + + private static string StableComponents(IEnumerable components) + { + return string.Join("|", components + .OrderBy(component => component.Type, StringComparer.Ordinal) + .Select(component => component.Type + "=" + StableMap(component.Properties))); + } + + private static string StableFloats(IEnumerable values) + { + return string.Join(",", values.Select(value => value.ToString("R", CultureInfo.InvariantCulture))); + } + + private static string StableMap(Dictionary values) + { + return string.Join("|", values + .OrderBy(pair => pair.Key, StringComparer.Ordinal) + .Select(pair => pair.Key + "=" + pair.Value)); + } + } +} diff --git a/src/GameCult.Mesh/README.md b/src/GameCult.Mesh/README.md index 4689136a..3bf3beb7 100644 --- a/src/GameCult.Mesh/README.md +++ b/src/GameCult.Mesh/README.md @@ -45,6 +45,23 @@ using var node = await CultMesh.StartNodeAsync("world.ccmp", new CultMeshNodeOpt If `ShardLogPath` is omitted, CultMesh stores logs beside the cache under `world.cultmesh/shard-logs`. +## Distributed CDN + +CultMesh can distribute signed, content-addressed game assets through the same +typed document lane as gameplay state. Asset manifests, chunks, and portable +entity prefab packages are CultCache documents that can be replicated by +CultNet snapshots, shard logs, central servers, LAN peers, or opted-out-capable +internet peer caches. + +This is the canonical asset pipeline target for Aetheria. Brokkr-authored +Blender prefab snapshots deploy into `CultMeshEntityPrefabPackage` documents +that reference CDN artifact manifests for meshes, textures, materials, and +other payloads. Unity and TypeScript clients should unpack the same package +graph rather than maintaining separate Unity-prefab and Electron asset formats. + +See [docs/distributed-cdn.md](docs/distributed-cdn.md) for document shapes, +publish/read helpers, peer asset sharing policy, and the Brokkr prefab flow. + ## Verses A Verse is a rule-bearing consensus graph. Aetheria Main can be a @@ -378,5 +395,6 @@ hot frame bodies remain in the cheapest storage both endpoints can share. - [Public API](docs/public-api.md) - [Durable Node Quickstart](docs/durable-node-quickstart.md) - [Typed Document Path](docs/typed-document-path.md) +- [Distributed CDN Documents](docs/distributed-cdn.md) - [Research Notes](docs/research.md) - [Verse Model](docs/verses.md) diff --git a/src/GameCult.Mesh/docs/distributed-cdn.md b/src/GameCult.Mesh/docs/distributed-cdn.md new file mode 100644 index 00000000..fef4e276 --- /dev/null +++ b/src/GameCult.Mesh/docs/distributed-cdn.md @@ -0,0 +1,197 @@ +# Distributed CDN Documents + +CultMesh CDN artifacts are typed CultCache documents, not a separate asset +transport. The same manifest and chunk records can be written by an asset +pipeline daemon, replicated through CultNet raw snapshots or shard logs, and +read by Unity, TypeScript, or another runtime that implements the CultCache +document contract. + +This is the canonical path for moving Aetheria assets into CultLib. Starbridge +Unity and Starbridge Electron should consume the same records so UI textures, +map icons, environment layers, shaders, and build payloads do not fork by +client. + +## Feature Overview + +The CDN feature has four layers: + +1. `CultMeshCdnArtifactManifest` describes one versioned payload. +2. `CultMeshCdnArtifactChunk` stores content-addressed payload bytes. +3. `CultMeshEntityPrefabPackage` describes a portable entity/prefab graph and + references CDN artifact manifests for meshes, textures, materials, animation, + audio, or other runtime payloads. +4. Mesh asset sharing moves those signed manifests and chunks through central + servers, LAN peers, or internet peers without granting peers authority over + game state. + +This is not a Unity asset bundle system and not a raw FBX distribution system. +Blender is the authoring ground truth for entity prefabs. Brokkr can mirror a +legacy Unity prefab into Blender for migration, but the deployed CDN artifact is +the Brokkr/Blender-authored snapshot lowered into CultMesh documents. + +Typical flow: + +1. Unity publishes a one-time `brokkr.unity.prefab_mirror_snapshot.v0` for an + existing prefab. +2. Brokkr Blender imports that snapshot into a collection so artists can + configure renderable entity requirements in Blender. +3. Brokkr Blender publishes a `brokkr.prefab.snapshot.v0` deploy snapshot from + the collection. +4. A deployer packages referenced meshes, textures, and materials as CDN + artifacts. +5. The deployer writes a `CultMeshEntityPrefabPackage` that references those CDN + artifact manifests. +6. Unity, TypeScript, and later clients fetch the same package and lower it into + their runtime entity/component model. + +## Document Shape + +`CultMeshCdnArtifactManifest` is the versioned asset handle. It carries: + +- `ArtifactId`: logical id, such as `aetheria/ui/icons/minimap`. +- `Kind`: `asset`, `build`, or `package`. +- `Version`: caller-defined release or content version. +- `ContentHash`: SHA-256 of the full materialized payload. +- `SizeBytes`: full payload size. +- `MimeType`: byte interpretation hint. +- `Chunks`: ordered `CultMeshCdnChunkRef` placements. +- `Tags` and `Metadata`: routing and domain hints. + +`CultMeshCdnArtifactChunk` is content-addressed by SHA-256. It carries only the +chunk hash, byte count, and raw payload. Placement is deliberately in the +manifest reference, so equal chunk bytes can be reused across assets and build +updates. + +## Runtime Contract + +Clients should: + +1. Fetch or receive a manifest by record key, tag, or index. +2. Fetch every chunk record referenced by `manifest.Chunks`. +3. Verify each chunk hash before copying bytes. +4. Reassemble chunks by `Offset`. +5. Verify the full `ContentHash`. +6. Interpret bytes according to `MimeType` plus domain metadata. + +Single-channel data stays single-channel. For example, a gravity map can use +raw bytes with metadata such as `channels=r32` instead of pretending to be an +RGBA texture. + +## Mesh Asset Sharing Policy + +CultMesh asset distribution is allowed to use installed clients as a peer asset +cache because Aetheria cannot assume enough central infrastructure to serve all +game files authoritatively. This must be visible to players and configurable in +the client, but the initial product policy is opt-out rather than opt-in. + +The default policy should be: + +- Local cache is always enabled. +- LAN asset sharing is enabled by default. +- Internet peer asset sharing is enabled by default for signed asset chunks and + prefab packages. +- Executable or build-update seeding is disabled by default until the UX and + signing story is mature. +- Uploading is disabled or heavily throttled during gameplay. +- Uploading has conservative default rate and daily caps. +- Metered, cellular, battery-constrained, VPN, or corporate-network cases should + disable or throttle peer upload when detectable. +- The client must expose a clear `Do not upload game assets to other players` + control. +- The client must expose telemetry: cache size, current upload/download rate, + bytes served to peers, and bytes received from peers. + +Suggested runtime configuration: + +```csharp +var policy = new MeshAssetSharingPolicy +{ + EnabledByDefault = true, + AllowLanPeers = true, + AllowInternetPeers = true, + AllowBuildArtifacts = false, + DisableDuringGameplay = true, + DisableOnMeteredNetwork = true, + RequireSignedManifests = true, + ShowStatusTelemetry = true +}; +``` + +Peers are never trusted as authority. They only serve bytes. Every chunk is +content-addressed, every artifact is reconstructed from a manifest, and game +clients must verify hashes and signatures before using the result. + +## C# Publishing + +```csharp +var artifact = CultMesh.PackCdnArtifact( + "aetheria/environment/gravity/ragnarok", + gravityBytes, + new CultMeshCdnPackOptions + { + Kind = CultMeshCdnArtifactKinds.Asset, + Version = "2026.06.27", + MimeType = "application/octet-stream", + Tags = ["aetheria", "environment", "gravity"], + Metadata = + { + ["channels"] = "r32", + ["width"] = "1024", + ["height"] = "1024" + } + }); + +await CultMesh.PublishCdnArtifactAsync(node.Cache, artifact); +``` + +For build distribution, use the same API with `Kind = CultMeshCdnArtifactKinds.Build` +and metadata such as `platform=windows-x64` or `channel=internal`. + +## CultNet Replication + +CDN documents use the regular raw document lane: + +```csharp +var registry = CultMesh.CreateCdnDocumentRegistry(node.Cache.Registry); +var request = registry.CreateSnapshotRequest( + "cdn-request", + schemaIds: + [ + node.Cache.Registry.GetRequired().SchemaId, + node.Cache.Registry.GetRequired().SchemaId + ], + recordKeys: artifact.RecordKeys.Select(key => key.Value)); + +var response = registry.CreateRawSnapshotResponse(node.Cache, "cdn-response", request); +``` + +The TypeScript client should mirror the C# schema names, schema versions, +record-key rules, chunk hashing, and verification order. C# remains the +reference implementation. + +## Entity Prefabs + +Entity prefabs are distributed as Brokkr-authored snapshots, then deployed into +portable CultMesh prefab packages. Brokkr's Blender UI publishes +`brokkr.prefab.snapshot.v0` records for a collection-scoped prefab. A deployer +can consume that snapshot, publish meshes/textures/material payloads as CDN +artifacts, and write a `CultMeshEntityPrefabPackage` that references those +artifact manifests. + +That keeps Blender as the authoring ground truth while avoiding Unity prefab +files as the interchange format. Unity, TypeScript, and later runtimes unpack +the same package graph into their native entity/component model. + +## Client Responsibilities + +Unity and TypeScript clients should implement the same rules: + +- Fetch prefab packages by record key, tag, or version catalog. +- Fetch every referenced artifact manifest and chunk. +- Verify signed manifests before trusting package membership. +- Verify chunk hashes and full artifact hashes before import. +- Cache artifacts locally by content hash. +- Lower package nodes into local runtime objects without writing back Unity-owned + or Electron-owned prefab truth. +- Respect `MeshAssetSharingPolicy` for peer upload, status telemetry, and + opt-out behavior. diff --git a/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs b/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs new file mode 100644 index 00000000..9a28a164 --- /dev/null +++ b/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs @@ -0,0 +1,123 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text; +using System.Threading.Tasks; +using FluentAssertions; +using GameCult.Caching; +using GameCult.Networking; +using NUnit.Framework; + +namespace GameCult.Mesh.Tests; + +public sealed class CultMeshCdnTests +{ + [Test] + public async Task Artifact_PacksPublishesAndReassembles_FromCultCache() + { + var cache = new CultCache(); + var payload = Encoding.UTF8.GetBytes("abcdefghijklmnopqrstuvwxyz"); + var artifact = CultMesh.PackCdnArtifact( + "aetheria/ui/icons/minimap-pack", + payload, + new CultMeshCdnPackOptions + { + ChunkSizeBytes = 8, + Version = "2026.06.27", + MimeType = "application/octet-stream", + Tags = ["aetheria", "ui"], + Metadata = new Dictionary + { + ["channel"] = "dev" + } + }); + + artifact.Manifest.Kind.Should().Be(CultMeshCdnArtifactKinds.Asset); + artifact.Manifest.SizeBytes.Should().Be(payload.Length); + artifact.Manifest.Chunks.Should().HaveCount(4); + artifact.Manifest.Chunks.Select(chunk => chunk.Offset).Should().Equal(0, 8, 16, 24); + artifact.Manifest.Chunks.Select(chunk => chunk.SizeBytes).Should().Equal(8, 8, 8, 2); + + var manifest = await CultMesh.PublishCdnArtifactAsync(cache, artifact); + var manifestKey = CultMeshCdnArtifactManifest.CreateRecordKey(manifest); + cache.Get(manifestKey).Should().NotBeNull(); + + var roundTrip = CultMesh.ReadCdnArtifact(cache, manifest); + roundTrip.Should().Equal(payload); + } + + [Test] + public async Task BuildArtifact_Replicates_ThroughCultNetRawSnapshot() + { + var sourceCache = new CultCache(); + var targetCache = new CultCache(); + var registry = CultMesh.CreateCdnDocumentRegistry(sourceCache.Registry); + var payload = Encoding.UTF8.GetBytes("starbridge-build-update"); + var artifact = CultMesh.PackCdnArtifact( + "starbridge/windows/client", + payload, + new CultMeshCdnPackOptions + { + ChunkSizeBytes = 7, + Kind = CultMeshCdnArtifactKinds.Build, + Version = "0.4.0-preview", + Tags = ["starbridge", "build"], + Metadata = new Dictionary + { + ["platform"] = "windows-x64" + } + }); + var manifest = await CultMesh.PublishCdnArtifactAsync(sourceCache, artifact); + var manifestSchemaId = sourceCache.Registry.GetRequired().SchemaId; + var chunkSchemaId = sourceCache.Registry.GetRequired().SchemaId; + var recordKeys = artifact.RecordKeys.Select(key => key.Value).ToArray(); + + var request = registry.CreateSnapshotRequest( + "cdn-snapshot-request", + schemaIds: [manifestSchemaId, chunkSchemaId], + recordKeys: recordKeys); + var response = registry.CreateRawSnapshotResponse(sourceCache, "cdn-snapshot", request); + + response.Documents.Should().HaveCount(artifact.Chunks.Count + 1); + response.Documents.Select(document => document.RecordKey).Should().BeEquivalentTo(recordKeys); + + await registry.ApplyRawSnapshotResponseAsync(targetCache, response); + var replicatedManifest = targetCache.Get( + CultMeshCdnArtifactManifest.CreateRecordKey(manifest)); + replicatedManifest.Should().NotBeNull(); + replicatedManifest!.Kind.Should().Be(CultMeshCdnArtifactKinds.Build); + replicatedManifest.Metadata["platform"].Should().Be("windows-x64"); + + var roundTrip = CultMesh.ReadCdnArtifact(targetCache, replicatedManifest); + roundTrip.Should().Equal(payload); + } + + [Test] + public async Task ArtifactRead_RejectsTamperedChunkPayload() + { + var cache = new CultCache(); + var artifact = CultMesh.PackCdnArtifact( + "aetheria/gravity/layer0", + [1, 1, 2, 3, 5, 8], + new CultMeshCdnPackOptions + { + ChunkSizeBytes = 3, + Metadata = new Dictionary + { + ["channels"] = "r32" + } + }); + var manifest = await CultMesh.PublishCdnArtifactAsync(cache, artifact); + var firstChunk = artifact.Chunks[0]; + firstChunk.Payload[0] = 99; + await cache.UpsertAsync( + firstChunk, + new CultRecordHandle( + CultMeshCdnArtifactChunk.CreateRecordKey(firstChunk))); + + Action read = () => CultMesh.ReadCdnArtifact(cache, manifest); + read.Should().Throw() + .WithMessage("*chunk hash*"); + } +} diff --git a/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs b/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs new file mode 100644 index 00000000..ec8bbcf7 --- /dev/null +++ b/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs @@ -0,0 +1,197 @@ +using System.Collections.Generic; +using System.Linq; +using System.Text; +using System.Threading.Tasks; +using FluentAssertions; +using GameCult.Caching; +using NUnit.Framework; + +namespace GameCult.Mesh.Tests; + +public sealed class CultMeshEntityPrefabTests +{ + [Test] + public async Task EntityPrefabPackage_PublishesBrokkrAuthoredGraph_WithCdnAssetRefs() + { + var cache = new CultCache(); + var meshArtifact = CultMesh.PackCdnArtifact( + "aetheria/prefabs/ships/scout/mesh/body", + Encoding.UTF8.GetBytes("portable-mesh-bytes"), + new CultMeshCdnPackOptions + { + Version = "authoring-1", + MimeType = "model/gltf-binary", + Tags = ["brokkr", "mesh"], + }); + var textureArtifact = CultMesh.PackCdnArtifact( + "aetheria/prefabs/ships/scout/texture/albedo", + Encoding.UTF8.GetBytes("texture-bytes"), + new CultMeshCdnPackOptions + { + Version = "authoring-1", + MimeType = "image/png", + Tags = ["brokkr", "texture"], + }); + await CultMesh.PublishCdnArtifactAsync(cache, meshArtifact); + await CultMesh.PublishCdnArtifactAsync(cache, textureArtifact); + + var package = CultMesh.FinalizeEntityPrefabPackage(new CultMeshEntityPrefabPackage + { + PrefabId = "aetheria/entity/ship/scout", + Version = "authoring-1", + SourceTool = "brokkr.blender", + SourceScene = "ships.blend", + SourceCollection = "prefab.ship.scout", + Tags = ["aetheria", "ship", "brokkr"], + Assets = + [ + AssetRef("mesh.body", CultMeshEntityPrefabAssetRoles.Mesh, meshArtifact.Manifest), + AssetRef("texture.albedo", CultMeshEntityPrefabAssetRoles.Texture, textureArtifact.Manifest) + ], + Nodes = + [ + new CultMeshEntityPrefabNode + { + NodeId = "root", + Name = "Scout", + Kind = CultMeshEntityPrefabNodeKinds.Empty, + Tags = ["entity-root"], + Components = + [ + new CultMeshEntityPrefabComponent + { + Type = "aetheria.ship", + Properties = new Dictionary + { + ["hullClass"] = "scout" + } + } + ] + }, + new CultMeshEntityPrefabNode + { + NodeId = "body", + Name = "Body", + ParentNodeId = "root", + Kind = CultMeshEntityPrefabNodeKinds.Mesh, + MeshAssetId = "mesh.body", + MaterialAssetIds = ["texture.albedo"], + Transform = new CultMeshEntityPrefabTransform + { + Position = [0f, 0f, 0f], + Rotation = [0f, 0f, 0f, 1f], + Scale = [1f, 1f, 1f] + } + } + ], + Metadata = new Dictionary + { + ["authoringAxis"] = "blender", + ["runtimeLowering"] = "unity,ts" + } + }); + + await CultMesh.PublishEntityPrefabPackageAsync(cache, package); + + var key = CultMeshEntityPrefabPackage.CreateRecordKey(package); + var stored = cache.Get(key); + stored.Should().NotBeNull(); + stored!.SourceTool.Should().Be("brokkr.blender"); + stored.SourceCollection.Should().Be("prefab.ship.scout"); + stored.Nodes.Should().Contain(node => node.Kind == CultMeshEntityPrefabNodeKinds.Mesh); + stored.Assets.Select(asset => asset.CdnManifestRecordKey) + .Should() + .Contain(meshArtifact.ManifestKey.Value) + .And.Contain(textureArtifact.ManifestKey.Value); + } + + [Test] + public async Task EntityPrefabPackage_ReplicatesWithReferencedCdnArtifacts_ThroughRawSnapshot() + { + var sourceCache = new CultCache(); + var targetCache = new CultCache(); + var registry = CultMesh.CreateAssetPipelineDocumentRegistry(sourceCache.Registry); + var meshArtifact = CultMesh.PackCdnArtifact( + "aetheria/prefabs/projectiles/bolt/mesh", + Encoding.UTF8.GetBytes("bolt-mesh"), + new CultMeshCdnPackOptions { Version = "v1", MimeType = "model/gltf-binary" }); + await CultMesh.PublishCdnArtifactAsync(sourceCache, meshArtifact); + + var package = CultMesh.FinalizeEntityPrefabPackage(new CultMeshEntityPrefabPackage + { + PrefabId = "aetheria/entity/projectile/bolt", + Version = "v1", + SourceTool = "brokkr.blender", + SourceScene = "projectiles.blend", + SourceCollection = "prefab.projectile.bolt", + Assets = [AssetRef("mesh", CultMeshEntityPrefabAssetRoles.Mesh, meshArtifact.Manifest)], + Nodes = + [ + new CultMeshEntityPrefabNode + { + NodeId = "bolt", + Name = "Bolt", + Kind = CultMeshEntityPrefabNodeKinds.Mesh, + MeshAssetId = "mesh", + Components = + [ + new CultMeshEntityPrefabComponent + { + Type = "aetheria.projectile", + Properties = new Dictionary + { + ["damage"] = "10" + } + } + ] + } + ] + }); + await CultMesh.PublishEntityPrefabPackageAsync(sourceCache, package); + + var packageSchema = sourceCache.Registry.GetRequired().SchemaId; + var manifestSchema = sourceCache.Registry.GetRequired().SchemaId; + var chunkSchema = sourceCache.Registry.GetRequired().SchemaId; + var recordKeys = new[] { CultMeshEntityPrefabPackage.CreateRecordKey(package) } + .Concat(meshArtifact.RecordKeys) + .Select(key => key.Value) + .ToArray(); + + var request = registry.CreateSnapshotRequest( + "entity-prefab-request", + schemaIds: [packageSchema, manifestSchema, chunkSchema], + recordKeys: recordKeys); + var response = registry.CreateRawSnapshotResponse(sourceCache, "entity-prefab-response", request); + + response.Documents.Should().HaveCount(meshArtifact.Chunks.Count + 2); + await registry.ApplyRawSnapshotResponseAsync(targetCache, response); + + var replicatedPackage = targetCache.Get( + CultMeshEntityPrefabPackage.CreateRecordKey(package)); + replicatedPackage.Should().NotBeNull(); + replicatedPackage!.Nodes.Single().Components.Single().Type.Should().Be("aetheria.projectile"); + + var meshManifest = targetCache.Get(meshArtifact.ManifestKey); + meshManifest.Should().NotBeNull(); + CultMesh.ReadCdnArtifact(targetCache, meshManifest!).Should().Equal(Encoding.UTF8.GetBytes("bolt-mesh")); + } + + private static CultMeshEntityPrefabAssetRef AssetRef( + string assetId, + string role, + CultMeshCdnArtifactManifest manifest) + { + return new CultMeshEntityPrefabAssetRef + { + AssetId = assetId, + Role = role, + CdnManifestRecordKey = CultMeshCdnArtifactManifest.CreateRecordKey(manifest).Value, + ContentHash = manifest.ContentHash, + MimeType = manifest.MimeType, + Metadata = new Dictionary + { + ["sourceArtifactId"] = manifest.ArtifactId + } + }; + } +}