Mostlylucid.Common 8.14.2

Mostlylucid.Common

Shared abstractions, base classes, and utilities for Mostlylucid NuGet packages.

Features

Caching

Generic caching service abstraction with memory cache implementation:

// Register caching service
services.AddMemoryCachingService<MyData>(options =>
{
    options.DefaultExpiration = TimeSpan.FromMinutes(30);
    options.MaxEntries = 5000;
});

// Use in your service
public class MyService
{
    private readonly ICachingService<MyData> _cache;

    public async Task<MyData?> GetDataAsync(string key)
    {
        return await _cache.GetOrAddAsync(key, async () =>
        {
            // Fetch from source if not cached
            return await FetchFromSourceAsync(key);
        });
    }
}

Statistics Tracking

Base interfaces and implementations for service statistics:

public class MyService : IServiceStatistics
{
    private readonly ServiceStatisticsTracker _stats = new();

    public async Task<Result> ProcessAsync(Request request)
    {
        _stats.IncrementRequests();

        var cached = GetFromCache(request);
        if (cached != null)
        {
            _stats.IncrementCacheHit();
            return cached;
        }

        // Process...
    }

    public long TotalRequests => _stats.TotalRequests;
    public long CacheHits => _stats.CacheHits;
    public double CacheHitRate => _stats.CacheHitRate;
}

Periodic Update Service

Base class for background services that periodically update data:

public class MyUpdateService : PeriodicUpdateService
{
    protected override TimeSpan UpdateInterval => TimeSpan.FromHours(24);

    protected override Task<DateTime?> GetLastUpdateTimeAsync(CancellationToken ct)
    {
        return Task.FromResult(File.GetLastWriteTimeUtc("data.db") as DateTime?);
    }

    protected override async Task PerformUpdateAsync(CancellationToken ct)
    {
        await DownloadLatestDataAsync(ct);
    }
}

Configuration Interfaces

Standard options interfaces for consistent configuration:

public class MyOptions : ICacheableOptions, ITestableOptions
{
    public bool Enabled { get; set; } = true;
    public TimeSpan CacheDuration { get; set; } = TimeSpan.FromHours(1);
    public int MaxCacheEntries { get; set; } = 10000;
    public bool EnableTestMode { get; set; } = false;
    public string TestModeHeader => "X-Test-Mode";
}

Middleware Base

Base class for middleware with test mode support:

public class MyMiddleware : TestModeMiddlewareBase<MyResult>
{
    protected override string ResultKey => "MyResult";
    protected override string TestModeHeader => "X-Test-Mode";
    protected override bool IsTestModeEnabled => _options.EnableTestMode;

    protected override MyResult? CreateTestModeResult(string testValue)
    {
        return new MyResult { TestValue = testValue };
    }

    protected override async Task<MyResult?> ProcessRequestAsync(HttpContext context)
    {
        var ip = context.GetClientIpAddress();
        return await _service.ProcessAsync(ip);
    }
}

IP Address Extraction

Helper for getting client IP addresses with proxy/CDN support:

// Automatically checks CF-Connecting-IP, X-Forwarded-For, X-Real-IP, etc.
var clientIp = context.GetClientIpAddress();

Entity Interfaces

Standard interfaces for database entities:

public class CachedItem : ICachedEntity
{
    public string Key { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
    public DateTime ExpiresAt { get; set; }
    public bool IsExpired => DateTime.UtcNow > ExpiresAt;
}

OpenTelemetry Support

Base classes and helpers for OpenTelemetry instrumentation across all Mostlylucid packages:

using Mostlylucid.Common.Telemetry;

// Get all Mostlylucid activity source names for OpenTelemetry configuration
var sources = TelemetryExtensions.GetMostlylucidActivitySourceNames();
foreach (var source in sources)
{
    tracing.AddSource(source);
}

// Activity source names are available as constants
// ActivitySources.BotDetection = "Mostlylucid.BotDetection"
// ActivitySources.GeoDetection = "Mostlylucid.GeoDetection"
// etc.

Available telemetry utilities:

• TelemetryActivitySource - Wrapper for System.Diagnostics.ActivitySource
• TelemetryOptions - Configuration for telemetry behavior
• TelemetryConstants - Standard attribute names following OpenTelemetry semantic conventions
• TelemetryExtensions - Helper methods for service registration
• ActivityExtensions - Extension methods for recording results and exceptions

Installation

dotnet add package Mostlylucid.Common

License

GNU AGPLv3