merge: SquidStd.Workers.Manager + workers e2e integration test (sub-project #4)

Author: tgiachi

SquidStd.slnx

@@ -21,6 +21,7 @@
         <Project Path="src/SquidStd.Templating/SquidStd.Templating.csproj" />
         <Project Path="src/SquidStd.Workers.Abstractions/SquidStd.Workers.Abstractions.csproj" />
         <Project Path="src/SquidStd.Workers/SquidStd.Workers.csproj" />
+        <Project Path="src/SquidStd.Workers.Manager/SquidStd.Workers.Manager.csproj" />
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />

docs/articles/toc.yml

@@ -38,6 +38,12 @@
   href: scripting-lua.md
 - name: SquidStd.Templating
   href: templating.md
+- name: SquidStd.Workers.Abstractions
+  href: workers-abstractions.md
+- name: SquidStd.Workers
+  href: workers.md
+- name: SquidStd.Workers.Manager
+  href: workers-manager.md
 - name: Serialization
   href: serialization.md
 - name: Scheduler

docs/articles/workers-abstractions.md

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

docs/articles/workers-manager.md

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

docs/articles/workers.md

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

src/SquidStd.Workers.Abstractions/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tgiachi/squid-std/main/assets/icon.png" alt="SquidStd" width="120" height="120" />
+</p>
+
+<h1 align="center">SquidStd.Workers.Abstractions</h1>
+
+<p align="center">
+  <a href="https://www.nuget.org/packages/SquidStd.Workers.Abstractions/"><img src="https://img.shields.io/nuget/v/SquidStd.Workers.Abstractions.svg" alt="NuGet" /></a>
+  <img src="https://img.shields.io/nuget/dt/SquidStd.Workers.Abstractions.svg" alt="Downloads" />
+  <a href="https://tgiachi.github.io/squid-std/articles/workers-abstractions.html"><img src="https://img.shields.io/badge/docs-DocFX-1390A3.svg" alt="docs" /></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" />
+</p>
+
+Shared, dependency-free contracts between the SquidStd worker runtime and manager: the job descriptor, the
+worker heartbeat, the manager-side worker view, the worker status enum, and the conventional channel names.
+
+## Install
+
+```bash
+dotnet add package SquidStd.Workers.Abstractions
+```
+
+## Key types
+
+| Type | Purpose |
+|------|---------|
+| `JobRequest` | A job (name + string parameters) enqueued by the manager and consumed by a worker. |
+| `WorkerHeartbeat` | Liveness signal a worker publishes (status, active jobs, max concurrency). |
+| `WorkerInfo` | The manager-side view of a worker, folded from heartbeats. |
+| `WorkerStatusType` | `Idle` / `Busy` / `Offline`. |
+| `WorkerChannels` | Default jobs-queue and heartbeat-topic names. |
+
+## License
+
+MIT — part of [SquidStd](https://github.com/tgiachi/squid-std).

src/SquidStd.Workers.Manager/Data/Config/WorkerManagerConfig.cs

@@ -0,0 +1,21 @@
+using SquidStd.Workers.Abstractions;
+
+namespace SquidStd.Workers.Manager.Data.Config;
+
+/// <summary>
+/// Configuration for the worker manager (config section "workerManager").
+/// </summary>
+public sealed class WorkerManagerConfig
+{
+    /// <summary>Seconds without a heartbeat before a worker is considered Offline. Falls back to 30 when not positive.</summary>
+    public int OfflineTimeoutSeconds { get; set; } = 30;
+
+    /// <summary>Seconds between offline sweeps. Falls back to 10 when not positive.</summary>
+    public int SweepIntervalSeconds { get; set; } = 10;
+
+    /// <summary>Queue jobs are enqueued onto.</summary>
+    public string JobQueue { get; set; } = WorkerChannels.JobQueue;
+
+    /// <summary>Topic heartbeats are collected from.</summary>
+    public string HeartbeatTopic { get; set; } = WorkerChannels.HeartbeatTopic;
+}

src/SquidStd.Workers.Manager/Data/EnqueueJobRequest.cs

@@ -0,0 +1,8 @@
+namespace SquidStd.Workers.Manager.Data;
+
+/// <summary>
+/// Request body for enqueuing a job via the manager's HTTP surface.
+/// </summary>
+/// <param name="JobName">Logical name of the job.</param>
+/// <param name="Parameters">Optional string key/value arguments; treated as empty when null.</param>
+public sealed record EnqueueJobRequest(string JobName, IReadOnlyDictionary<string, string>? Parameters);

src/SquidStd.Workers.Manager/Data/Events/WorkerStatusChangedEvent.cs

@@ -0,0 +1,13 @@
+using SquidStd.Core.Interfaces.Events;
+using SquidStd.Workers.Abstractions.Types;
+
+namespace SquidStd.Workers.Manager.Data.Events;
+
+/// <summary>
+/// Published on the event bus when a worker's status changes: discovered (<paramref name="OldStatus" /> null),
+/// gone Offline (via the sweep), or returned (Offline → Idle/Busy).
+/// </summary>
+/// <param name="WorkerId">The worker whose status changed.</param>
+/// <param name="OldStatus">Previous status, or <c>null</c> when the worker was just discovered.</param>
+/// <param name="NewStatus">The new status.</param>
+public sealed record WorkerStatusChangedEvent(string WorkerId, WorkerStatusType? OldStatus, WorkerStatusType NewStatus) : IEvent;

src/SquidStd.Workers.Manager/Endpoints/WorkerManagerEndpoints.cs

@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Http.HttpResults;
+using SquidStd.Workers.Abstractions.Data;
+using SquidStd.Workers.Manager.Data;
+using SquidStd.Workers.Manager.Interfaces;
+
+namespace SquidStd.Workers.Manager.Endpoints;
+
+/// <summary>
+/// Typed minimal-API handlers for the worker manager surface. Static so they can be unit-tested directly.
+/// </summary>
+public static class WorkerManagerEndpoints
+{
+    /// <summary>Lists all known workers.</summary>
+    public static Ok<IReadOnlyCollection<WorkerInfo>> GetWorkers(IWorkerRegistry registry)
+        => TypedResults.Ok(registry.GetAll());
+
+    /// <summary>Returns a single worker, or 404 when unknown.</summary>
+    public static Results<Ok<WorkerInfo>, NotFound> GetWorker(string id, IWorkerRegistry registry)
+    {
+        var info = registry.Get(id);
+
+        return info is null ? TypedResults.NotFound() : TypedResults.Ok(info);
+    }
+
+    /// <summary>Enqueues a job; 400 on a blank name, 503 when the queue is unavailable.</summary>
+    public static async Task<Results<Accepted, BadRequest<string>, ProblemHttpResult>> EnqueueJob(
+        EnqueueJobRequest request,
+        IJobScheduler scheduler,
+        CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(request.JobName))
+        {
+            return TypedResults.BadRequest("JobName is required.");
+        }
+
+        try
+        {
+            await scheduler.EnqueueAsync(request.JobName, request.Parameters ?? new Dictionary<string, string>(), cancellationToken);
+
+            return TypedResults.Accepted((string?)null);
+        }
+        catch (Exception)
+        {
+            return TypedResults.Problem(statusCode: StatusCodes.Status503ServiceUnavailable, detail: "Job queue unavailable.");
+        }
+    }
+}