[FEATURE] Background jobs

Directory.Packages.props

@@ -14,9 +14,16 @@
     <PackageVersion Include="FluentAssertions" Version="8.8.0" />
     <PackageVersion Include="JunitXml.TestLogger" Version="8.0.0" />
     <PackageVersion Include="log4net" Version="3.3.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.Hosting.Abstractions" Version="2.2.0" />
+    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.EntityFrameworkCore.Relational" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="2.2.0" />
     <PackageVersion Include="Microsoft.Extensions.Http" Version="10.0.2" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="2.2.0" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.3.1" />
     <PackageVersion Include="NEST" Version="7.17.5" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <PackageVersion Include="NSubstitute" Version="5.3.0" />
@@ -35,4 +42,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageVersion>
   </ItemGroup>
-</Project>
+</Project>

Src/CrispyWaffle.BackgroundJobs/Abstractions/IBackgroundJob.cs

@@ -0,0 +1,13 @@
+using CrispyWaffle.BackgroundJobs.Core;
+
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    /// <summary>
+    /// Low-level job representation (mostly used for in-memory workflows).
+    /// For persisted jobs, prefer IBackgroundJobHandler<TData> with registry-based activation.
+    /// </summary>
+    public interface IBackgroundJob
+    {
+        Task<JobResult> ExecuteAsync(CancellationToken cancellationToken);
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/IBackgroundJobHandler.cs

@@ -0,0 +1,13 @@
+using CrispyWaffle.BackgroundJobs.Core;
+
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    /// <summary>
+    /// Typed handler used by persisted jobs. Implement this to allow DI-resolved handlers.
+    /// TData is the payload type stored as JSON in the job store.
+    /// </summary>
+    public interface IBackgroundJobHandler<TData>
+    {
+        Task<JobResult> HandleAsync(TData data, CancellationToken cancellationToken);
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/IJobScheduler.cs

@@ -0,0 +1,9 @@
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    public interface IJobScheduler
+    {
+        Task ScheduleAsync(string handlerName, object payload, TimeSpan delay, int maxAttempts = 3, JobPriority priority = JobPriority.Normal);
+
+        Task EnqueueAsync(string handlerName, object payload, int maxAttempts = 3, JobPriority priority = JobPriority.Normal);
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/IJobStore.cs

@@ -0,0 +1,19 @@
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    public interface IJobStore
+    {
+        Task SaveAsync(JobEntity job, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Fetch the next available job that is due (ScheduledAt <= UtcNow) and Pending.
+        /// Implementation should atomically mark it as Processing to avoid double pick-up.
+        /// </summary>
+        Task<JobEntity?> FetchNextAsync(CancellationToken cancellationToken = default);
+
+        Task MarkCompletedAsync(Guid jobId, CancellationToken cancellationToken = default);
+
+        Task MarkFailedAsync(Guid jobId, string error, CancellationToken cancellationToken = default);
+
+        Task MarkRetryAsync(Guid jobId, DateTimeOffset? nextAttemptAt, int attemptCount, CancellationToken cancellationToken = default);
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/JobEntity.cs

@@ -0,0 +1,47 @@
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    using System;
+
+    /// <summary>
+    /// Persistent representation of a job.
+    /// HandlerName identifies a registered handler; Payload is JSON.
+    /// </summary>
+    public class JobEntity
+    {
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        /// <summary>
+        /// Logical handler name registered in IJobHandlerRegistry.
+        /// </summary>
+        public string HandlerName { get; set; } = string.Empty;
+
+        /// <summary>
+        /// JSON payload (serialized) for the handler.
+        /// </summary>
+        public string Payload { get; set; } = string.Empty;
+
+        public JobPriority Priority { get; set; } = JobPriority.Normal;
+
+        public JobStatus Status { get; set; } = JobStatus.Pending;
+
+        /// <summary>
+        /// When the job becomes due for execution. Null means immediately.
+        /// </summary>
+        public DateTimeOffset? ScheduledAt { get; set; }
+
+        public int Attempt { get; set; } = 0;
+
+        public int MaxAttempt { get; set; } = 3;
+
+        public string? LastError { get; set; }
+
+        public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
+
+        public DateTimeOffset UpdatedAt { get; set; } = DateTimeOffset.UtcNow;
+
+        /// <summary>
+        /// Optional delay in seconds between retries (used only as hint).
+        /// </summary>
+        public int RetryDelaySeconds { get; set; } = 0;
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/JobPriority.cs

@@ -0,0 +1,9 @@
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    public enum JobPriority
+    {
+        High = 0,
+        Normal = 1,
+        Low = 2
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Abstractions/JobStatus.cs

@@ -0,0 +1,11 @@
+namespace CrispyWaffle.BackgroundJobs.Abstractions
+{
+    public enum JobStatus
+    {
+        Pending = 0,
+        Processing = 1,
+        Completed = 2,
+        Failed = 3,
+        Dead = 4
+    }
+}

Src/CrispyWaffle.BackgroundJobs/Core/BackgroundJobQueue.cs

@@ -0,0 +1,47 @@
+using CrispyWaffle.BackgroundJobs.Abstractions;
+using System.Threading.Channels;
+
+namespace CrispyWaffle.BackgroundJobs.Core
+{
+    /// <summary>
+    /// Lightweight in-memory priority queue using Channel for signaling.
+    /// Priorities: lower int = higher priority.
+    /// This queue stores JobEntity (for uniformity with persistent store model).
+    /// </summary>
+    public class BackgroundJobQueue
+    {
+        private readonly object _lock = new();
+        private readonly PriorityQueue<JobEntity, int> _pq = new();
+        private readonly Channel<JobEntity> _signal = Channel.CreateUnbounded<JobEntity>(new UnboundedChannelOptions { SingleReader = false, SingleWriter = false });
+
+        public void Enqueue(JobEntity job)
+        {
+            lock (_lock)
+            {
+                _pq.Enqueue(job, (int)job.Priority);
+            }
+            // Always write to signal channel to notify consumers.
+            _ = _signal.Writer.WriteAsync(job);
+        }
+
+        public async Task<JobEntity?> DequeueAsync(CancellationToken cancellationToken)
+        {
+            // Wait until a job is signaled and then pop from our priority queue.
+            try
+            {
+                await _signal.Reader.ReadAsync(cancellationToken);
+            }
+            catch (OperationCanceledException) { return null; }
+
+            lock (_lock)
+            {
+                if (_pq.TryDequeue(out var job, out _))
+                {
+                    return job;
+                }
+            }
+
+            return null;
+        }
+    }
+}