Release: Health Checks, Storage (file + S3), and ASP.NET Core health bridge

README.md

@@ -68,9 +68,9 @@ block until cancellation for long-running hosts.
 
 | Package | Description | Links |
 |---------|-------------|-------|
-| `SquidStd.Core` | Foundational contracts & utilities (config, event bus, jobs, metrics, storage, YAML/JSON, Serilog sink). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Core.svg)](https://www.nuget.org/packages/SquidStd.Core/) |
+| `SquidStd.Core` | Foundational contracts & utilities (config, event bus, jobs, metrics, serialization, YAML/JSON, Serilog sink). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Core.svg)](https://www.nuget.org/packages/SquidStd.Core/) |
 | `SquidStd.Abstractions` | DI registration plumbing (`ISquidStdService`, `RegisterStdService`, `RegisterConfigSection`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Abstractions/) |
-| `SquidStd.Services.Core` | Concrete services: config, event bus, jobs, timer/cron scheduler, dispatcher, metrics, storage. | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Services.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Services.Core.svg)](https://www.nuget.org/packages/SquidStd.Services.Core/) |
+| `SquidStd.Services.Core` | Concrete services: config, event bus, jobs, timer/cron scheduler, dispatcher, metrics, health checks, secrets. | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Services.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Services.Core.svg)](https://www.nuget.org/packages/SquidStd.Services.Core/) |
 | `SquidStd.AspNetCore` | ASP.NET Core host integration for the SquidStd service stack. | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.AspNetCore/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.AspNetCore.svg)](https://www.nuget.org/packages/SquidStd.AspNetCore/) |
 | `SquidStd.Network` | TCP/UDP servers & clients, sessions, framing/middleware pipeline, span readers/writers. | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Network/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Network.svg)](https://www.nuget.org/packages/SquidStd.Network/) |
 | `SquidStd.Plugin.Abstractions` | Plugin contracts (`ISquidStdPlugin`, metadata, context). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Plugin.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Plugin.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Plugin.Abstractions/) |
@@ -82,6 +82,9 @@ block until cancellation for long-running hosts.
 | `SquidStd.Caching.Abstractions` | Caching contracts (`ICacheService`, `ICacheProvider`, `CacheService` facade, metrics, connection string). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Caching.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Caching.Abstractions/) |
 | `SquidStd.Caching` | In-memory cache backend (`AddInMemoryCache`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Caching/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.svg)](https://www.nuget.org/packages/SquidStd.Caching/) |
 | `SquidStd.Caching.Redis` | Redis cache backend (`AddRedisCache`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Caching.Redis/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.Redis.svg)](https://www.nuget.org/packages/SquidStd.Caching.Redis/) |
+| `SquidStd.Storage.Abstractions` | Storage contracts (`IStorageService`, `IObjectStorageService`, `StorageConfig`, `ListKeysAsync`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Storage.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Storage.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Storage.Abstractions/) |
+| `SquidStd.Storage` | Local file storage backend (`AddFileStorage`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Storage/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Storage.svg)](https://www.nuget.org/packages/SquidStd.Storage/) |
+| `SquidStd.Storage.S3` | S3/MinIO storage backend (`AddS3Storage`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Storage.S3/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Storage.S3.svg)](https://www.nuget.org/packages/SquidStd.Storage.S3/) |
 | `SquidStd.Scripting.Lua` | Lua scripting engine with attribute-based modules and event bridging. | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Scripting.Lua/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Scripting.Lua.svg)](https://www.nuget.org/packages/SquidStd.Scripting.Lua/) |
 
 ## Architecture
@@ -102,7 +105,7 @@ squid-std follows a few consistent principles across every module:
 ## Documentation
 
 Full API documentation is published with DocFX to GitHub Pages:
-**[tgiachi.github.io/SquidStd](https://tgiachi.github.io/SquidStd/)**. Each package also ships its
+**[tgiachi.github.io/squid-std](https://tgiachi.github.io/squid-std/)**. Each package also ships its
 own README (linked in the table above).
 
 ## Build

SquidStd.slnx

@@ -15,6 +15,9 @@
         <Project Path="src/SquidStd.Plugin.Abstractions/SquidStd.Plugin.Abstractions.csproj" />
         <Project Path="src/SquidStd.Scripting.Lua/SquidStd.Scripting.Lua.csproj" />
         <Project Path="src/SquidStd.Services.Core/SquidStd.Services.Core.csproj" />
+        <Project Path="src/SquidStd.Storage.Abstractions/SquidStd.Storage.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Storage.S3/SquidStd.Storage.S3.csproj" />
+        <Project Path="src/SquidStd.Storage/SquidStd.Storage.csproj" />
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />

docs/articles/health-checks.md

@@ -0,0 +1,29 @@
+# Health Checks
+
+The health-check aggregator (`IHealthCheckService` in `SquidStd.Core`, implemented in
+`SquidStd.Services.Core`) runs every registered `IHealthCheck` and returns a single `HealthReport`.
+
+- Implement `IHealthCheck` (`Name` + `CheckAsync`) and register it as `IHealthCheck`.
+- `CheckHealthAsync()` runs all checks **in parallel**, each with a per-check timeout and exception
+  isolation — a failing or timed-out check becomes an `Unhealthy` entry without breaking the others.
+- The overall `HealthReport.Status` is `Unhealthy` if any check is `Unhealthy`, otherwise `Healthy`.
+
+```csharp
+using DryIoc;
+using SquidStd.Core.Data.Health;
+using SquidStd.Core.Interfaces.Health;
+using SquidStd.Services.Core.Extensions;
+
+container.RegisterHealthChecksService();
+
+var health = container.Resolve<IHealthCheckService>();
+HealthReport report = await health.CheckHealthAsync();
+
+if (report.Status == SquidStd.Core.Types.Health.HealthStatus.Unhealthy)
+{
+    foreach (var (name, result) in report.Entries)
+    {
+        Console.WriteLine($"{name}: {result.Status} {result.Description}");
+    }
+}
+```

docs/articles/scheduler.md

@@ -0,0 +1,29 @@
+# Scheduler (Cron)
+
+`ICronScheduler` (in `SquidStd.Core`, implemented in `SquidStd.Services.Core`) runs asynchronous jobs on
+standard 5-field cron expressions evaluated in UTC.
+
+- `Schedule(name, cronExpression, handler)` → returns a job id.
+- `Unschedule(jobId)` / `UnscheduleByName(name)`.
+- `Jobs` — a snapshot of registered jobs (`CronJobInfo`).
+
+Each job is a one-shot, self-rescheduling timer on the timer wheel: when it fires, the handler is
+dispatched through `IJobSystem`, and the next occurrence is registered. An occurrence is **skipped** if the
+previous run of the same job is still in flight. Because the timer wheel must be advanced, the package also
+provides `TimerWheelPumpService`, which pumps the wheel on a background loop.
+
+Register everything (after `RegisterCoreServices`) with `RegisterSchedulerServices()`:
+
+```csharp
+using DryIoc;
+using SquidStd.Core.Interfaces.Scheduling;
+using SquidStd.Services.Core.Extensions;
+
+container.RegisterSchedulerServices();
+
+var scheduler = container.Resolve<ICronScheduler>();
+scheduler.Schedule("cleanup", "0 3 * * *", async ct =>
+{
+    await DoCleanupAsync(ct);
+});
+```

docs/articles/serialization.md

@@ -0,0 +1,28 @@
+# Serialization
+
+SquidStd uses a single serialization abstraction across the framework, defined in `SquidStd.Core`:
+
+- `IDataSerializer` — `ReadOnlyMemory<byte> Serialize<T>(T value)`
+- `IDataDeserializer` — `T Deserialize<T>(ReadOnlyMemory<byte> data)`
+
+The default implementation, `JsonDataSerializer`, uses `System.Text.Json` Web defaults and implements
+both interfaces. It is registered by `RegisterCoreServices()` (via `RegisterDataSerializer()`), so both
+contracts resolve to the same singleton. Messaging and caching reuse it for payload (de)serialization.
+
+```csharp
+using DryIoc;
+using SquidStd.Core.Interfaces.Serialization;
+using SquidStd.Services.Core.Extensions;
+
+var container = new Container();
+container.RegisterDataSerializer();
+
+var serializer = container.Resolve<IDataSerializer>();
+var deserializer = container.Resolve<IDataDeserializer>();
+
+var bytes = serializer.Serialize(new { Name = "squid", Port = 9000 });
+var value = deserializer.Deserialize<Dictionary<string, object>>(bytes);
+```
+
+To plug in a different format, implement `IDataSerializer` / `IDataDeserializer` and register your type
+before `RegisterCoreServices()` (it keeps an already-registered serializer).

docs/articles/storage-abstractions.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Storage.Abstractions/README.md)]

docs/articles/storage-s3.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Storage.S3/README.md)]

docs/articles/storage.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Storage/README.md)]

docs/articles/toc.yml

@@ -28,5 +28,17 @@
   href: caching.md
 - name: SquidStd.Caching.Redis
   href: caching-redis.md
+- name: SquidStd.Storage.Abstractions
+  href: storage-abstractions.md
+- name: SquidStd.Storage
+  href: storage.md
+- name: SquidStd.Storage.S3
+  href: storage-s3.md
 - name: SquidStd.Scripting.Lua
   href: scripting-lua.md
+- name: Serialization
+  href: serialization.md
+- name: Scheduler
+  href: scheduler.md
+- name: Health Checks
+  href: health-checks.md

src/SquidStd.AspNetCore/Extensions/SquidStdAspNetCoreBuilderExtensions.cs

@@ -48,6 +48,7 @@ public WebApplicationBuilder UseSquidStd(
             var container = new Container();
             builder.Host.UseServiceProviderFactory(new DryIocServiceProviderFactory(container));
             SquidStdBootstrap.Create(options, container);
+            builder.Host.Properties[ContainerPropertyKey] = container;
 
             var configuredContainer = configureContainer?.Invoke(container) ?? container;
 
@@ -62,6 +63,8 @@ public WebApplicationBuilder UseSquidStd(
         }
     }
 
+    internal const string ContainerPropertyKey = "SquidStd:Container";
+
     private static void ValidateOptions(SquidStdOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);

src/SquidStd.AspNetCore/Extensions/SquidStdHealthChecksExtensions.cs

@@ -0,0 +1,53 @@
+using DryIoc;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Hosting;
+using SquidStd.AspNetCore.Services;
+using SquidHealthCheck = SquidStd.Core.Interfaces.Health.IHealthCheck;
+
+namespace SquidStd.AspNetCore.Extensions;
+
+/// <summary>
+/// Extension methods that bridge SquidStd health checks into the standard ASP.NET Core health-check system.
+/// </summary>
+public static class SquidStdHealthChecksExtensions
+{
+    /// <param name="builder">ASP.NET Core application builder.</param>
+    extension(WebApplicationBuilder builder)
+    {
+        /// <summary>
+        /// Registers each SquidStd <c>IHealthCheck</c> as a standard ASP.NET Core health check (one entry
+        /// per check, same name). Call after <c>UseSquidStd</c>; expose them with the standard
+        /// <c>app.MapHealthChecks(...)</c>. Check names must be unique.
+        /// </summary>
+        /// <returns>The same builder for chaining.</returns>
+        public WebApplicationBuilder AddSquidStdHealthChecks()
+        {
+            ArgumentNullException.ThrowIfNull(builder);
+
+            if (!builder.Host.Properties.TryGetValue(SquidStdAspNetCoreBuilderExtensions.ContainerPropertyKey, out var value)
+                || value is not IContainer container)
+            {
+                throw new InvalidOperationException("Call UseSquidStd before AddSquidStdHealthChecks.");
+            }
+
+            var checks = container.Resolve<IEnumerable<SquidHealthCheck>>();
+            var healthChecks = builder.Services.AddHealthChecks();
+
+            foreach (var check in checks)
+            {
+                healthChecks.Add(
+                    new HealthCheckRegistration(
+                        check.Name,
+                        _ => new SquidStdHealthCheckAdapter(check),
+                        failureStatus: HealthStatus.Unhealthy,
+                        tags: null
+                    )
+                );
+            }
+
+            return builder;
+        }
+    }
+}

src/SquidStd.AspNetCore/README.md

@@ -27,6 +27,7 @@ dotnet add package SquidStd.AspNetCore
 - Configures DryIoc as the host's service-provider factory.
 - Registers `SquidStdHostedService` to start/stop SquidStd services with the host.
 - Optional `SquidStdOptions` configuration callback.
+- `WebApplicationBuilder.AddSquidStdHealthChecks()` — bridges every SquidStd `IHealthCheck` into the standard ASP.NET Core health-check system (one entry per check), exposed via the standard `app.MapHealthChecks(...)`.
 
 ## Usage
 
@@ -44,12 +45,30 @@ var app = builder.Build();
 app.Run();
 ```
 
+### Health checks
+
+Bridge your SquidStd health checks into the standard `/health` endpoint:
+
+```csharp
+using SquidStd.AspNetCore.Extensions;
+using SquidStd.Services.Core.Extensions;
+
+builder.UseSquidStd(options => { }, container => container.RegisterHealthChecksService());
+builder.AddSquidStdHealthChecks(); // call after UseSquidStd
+
+var app = builder.Build();
+app.MapHealthChecks("/health"); // standard ASP.NET Core endpoint
+```
+
+Each registered `IHealthCheck` appears as its own entry in the report. Check names must be unique.
+
 ## Key types
 
 | Type | Purpose |
 |------|---------|
 | `SquidStdAspNetCoreBuilderExtensions` | `UseSquidStd(...)` builder extension. |
 | `SquidStdHostedService` | Hosted service bridging SquidStd service lifecycle to the host. |
+| `SquidStdHealthChecksExtensions` | `AddSquidStdHealthChecks(...)` — bridge to ASP.NET Core health checks. |
 
 ## License
 

src/SquidStd.AspNetCore/Services/SquidStdHealthCheckAdapter.cs

@@ -0,0 +1,31 @@
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using SquidHealthCheck = SquidStd.Core.Interfaces.Health.IHealthCheck;
+using SquidHealthStatus = SquidStd.Core.Types.Health.HealthStatus;
+
+namespace SquidStd.AspNetCore.Services;
+
+/// <summary>
+/// Adapts a SquidStd <see cref="SquidHealthCheck" /> to the standard ASP.NET Core
+/// <see cref="IHealthCheck" /> contract.
+/// </summary>
+internal sealed class SquidStdHealthCheckAdapter : IHealthCheck
+{
+    private readonly SquidHealthCheck _check;
+
+    public SquidStdHealthCheckAdapter(SquidHealthCheck check)
+    {
+        _check = check;
+    }
+
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default
+    )
+    {
+        var result = await _check.CheckAsync(cancellationToken);
+
+        return result.Status == SquidHealthStatus.Unhealthy
+                   ? HealthCheckResult.Unhealthy(result.Description, result.Exception)
+                   : HealthCheckResult.Healthy(result.Description);
+    }
+}

src/SquidStd.Core/Data/Config/HealthCheckOptions.cs

@@ -0,0 +1,10 @@
+namespace SquidStd.Core.Data.Config;
+
+/// <summary>
+/// Options for the health-check aggregator.
+/// </summary>
+public sealed class HealthCheckOptions
+{
+    /// <summary>Per-check timeout. A check exceeding it is reported unhealthy. Default 5 seconds.</summary>
+    public TimeSpan CheckTimeout { get; set; } = TimeSpan.FromSeconds(5);
+}

src/SquidStd.Core/Data/Health/HealthCheckResult.cs

@@ -0,0 +1,29 @@
+using SquidStd.Core.Types.Health;
+
+namespace SquidStd.Core.Data.Health;
+
+/// <summary>
+/// Result of a single health check. <see cref="Duration" /> is stamped by the aggregator.
+/// </summary>
+public sealed record HealthCheckResult
+{
+    /// <summary>Health status of the check.</summary>
+    public required HealthStatus Status { get; init; }
+
+    /// <summary>Optional human-readable description.</summary>
+    public string? Description { get; init; }
+
+    /// <summary>Optional exception captured when the check failed.</summary>
+    public Exception? Exception { get; init; }
+
+    /// <summary>How long the check took.</summary>
+    public TimeSpan Duration { get; init; }
+
+    /// <summary>Creates a healthy result.</summary>
+    public static HealthCheckResult Healthy(string? description = null)
+        => new() { Status = HealthStatus.Healthy, Description = description };
+
+    /// <summary>Creates an unhealthy result.</summary>
+    public static HealthCheckResult Unhealthy(string? description = null, Exception? exception = null)
+        => new() { Status = HealthStatus.Unhealthy, Description = description, Exception = exception };
+}

src/SquidStd.Core/Data/Health/HealthReport.cs

@@ -0,0 +1,21 @@
+using SquidStd.Core.Types.Health;
+
+namespace SquidStd.Core.Data.Health;
+
+/// <summary>
+/// Aggregated result of running every registered health check.
+/// </summary>
+public sealed record HealthReport
+{
+    /// <summary>Overall status (unhealthy if any entry is unhealthy).</summary>
+    public required HealthStatus Status { get; init; }
+
+    /// <summary>Per-check results keyed by check name.</summary>
+    public required IReadOnlyDictionary<string, HealthCheckResult> Entries { get; init; }
+
+    /// <summary>Wall-clock time taken to run all checks.</summary>
+    public TimeSpan TotalDuration { get; init; }
+
+    /// <summary>UTC timestamp when the report was produced.</summary>
+    public DateTime TimestampUtc { get; init; }
+}

src/SquidStd.Core/Interfaces/Health/IHealthCheck.cs

@@ -0,0 +1,16 @@
+using SquidStd.Core.Data.Health;
+
+namespace SquidStd.Core.Interfaces.Health;
+
+/// <summary>
+/// A single health check for one component.
+/// </summary>
+public interface IHealthCheck
+{
+    /// <summary>Logical check name (used as the report entry key).</summary>
+    string Name { get; }
+
+    /// <summary>Runs the check.</summary>
+    /// <param name="cancellationToken">Token used to cancel the check (also fires on per-check timeout).</param>
+    ValueTask<HealthCheckResult> CheckAsync(CancellationToken cancellationToken = default);
+}

src/SquidStd.Core/Interfaces/Health/IHealthCheckService.cs

@@ -0,0 +1,12 @@
+using SquidStd.Core.Data.Health;
+
+namespace SquidStd.Core.Interfaces.Health;
+
+/// <summary>
+/// Runs every registered <see cref="IHealthCheck" /> and aggregates the results.
+/// </summary>
+public interface IHealthCheckService
+{
+    /// <summary>Runs all checks and returns the aggregated report.</summary>
+    ValueTask<HealthReport> CheckHealthAsync(CancellationToken cancellationToken = default);
+}