Cuemon.Data.Integrity

Overview

Cuemon.Data.Integrity models the integrity of entity and resource data as a combination of checksum state, timestamps, and validation strength. It gives you concrete types for building cache validators in memory and factory entry points for deriving the same model from files or assemblies.

The package centers on CacheValidator and ChecksumBuilder, then layers file and assembly conversion on top through DataIntegrityFactory and CacheValidatorFactory. It fits scenarios where a checksum alone is not enough because callers also need to know how fresh a resource is and how strong the underlying validation signal is.

Key APIs

CacheValidator is the main concrete model for cache-aware integrity tokens. It inherits from ChecksumBuilder, implements IEntityInfo, carries Created, Modified, Method, and Validation, and can collapse entity metadata into unaltered, timestamp-only, or combined checksum representations.

CacheValidatorFactory.CreateValidator(FileInfo, ...) and CacheValidatorFactory.CreateValidator(Assembly, ...) turn files or assemblies into CacheValidator instances. The factory reads a configurable byte range, chooses a default non-cryptographic hash based on that range, and falls back to name-based hashes when there is no file content to read.

ChecksumBuilder is the lower-level fluent base class for arbitrary checksum composition. It stores the accumulated byte sequence, computes the HashResult lazily, supports incremental CombineWith(byte[]), and treats equality as checksum equality rather than reference identity.

DataIntegrityFactory.CreateIntegrity(FileInfo, ...) is the file-to-model conversion primitive behind the higher-level factory. It reads the requested byte count from a FileInfo, hands those bytes to an IntegrityConverter, and lets callers decide which IDataIntegrity implementation should be produced.

EntityInfo is the simple metadata carrier for resource timestamps, checksum bytes, and validation strength. It normalizes Created and Modified to UTC and packages them together with a HashResult so a validator or other IDataIntegrity implementation can consume a single object.

EntityDataIntegrityMethod controls how CacheValidator interprets the underlying entity data. Unaltered keeps the provided checksum bytes, Timestamp derives the token from the timestamp values, and Combined folds timestamps together with the supplied checksum into one cache-oriented value.

FileChecksumOptions and FileIntegrityOptions are the configuration entry points for the factory APIs. FileChecksumOptions adds the Method switch for cache-validator generation, while FileIntegrityOptions requires a non-null IntegrityConverter so the low-level factory fails fast when no conversion strategy is supplied.

Basic usage

using System.Reflection;
using Codebelt.Extensions.Xunit;
using Cuemon.Data.Integrity;
using Xunit;

namespace MyProject.Tests;

public class CacheValidatorFactoryTest : Test
{
    public CacheValidatorFactoryTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ShouldCreateTimestampBasedValidatorFromAssembly()
    {
        Assembly assembly = typeof(CacheValidator).Assembly;

        CacheValidator validator = CacheValidatorFactory.CreateValidator(
            assembly,
            setup: options => options.Method = EntityDataIntegrityMethod.Timestamp);

        CacheValidator winner = CacheValidator.GetMostSignificant(CacheValidator.Default, validator);

        Assert.Equal(EntityDataIntegrityMethod.Timestamp, validator.Method);
        Assert.NotEqual(CacheValidator.Default.ToString(), validator.ToString());
        Assert.Equal(validator.ToString(), winner.ToString());

        TestOutput.WriteLine($"Assembly checksum: {validator}");
    }
}

Use this pattern when you need a cache token from a real assembly or file-backed resource without hardcoding the hashing workflow yourself. It matters because the package keeps timestamp comparison and checksum generation in one model, so freshness decisions and cache identifiers come from the same API.

Installation

dotnet add package Cuemon.Data.Integrity

Usage guidance

Adopt Cuemon.Data.Integrity when you need a first-class integrity model that combines timestamps, checksum state, and cache validation semantics for entities, files, or assemblies. If you only need low-level file option types, stay with Cuemon.IO, and if you only need a raw hash without entity metadata or cache comparison behavior, a lower-level hashing API is the better fit.