Arkn.Jobs 0.3.2

Arkn.Jobs

Zero-dependency cron scheduler with retry, timeout, distributed lock, persistence, and DLQ — wired into Arkn.Notifications.

Install

dotnet add package Arkn.Jobs

Setup

builder.Services.AddArknJobs(jobs =>
{
    jobs.Add<InvoiceProcessorJob>("0 2 * * *")
        .WithName("invoice-processor")
        .WithDescription("Processes pending invoices at 02:00")
        .WithTimeout(TimeSpan.FromMinutes(10))
        .WithRetry(maxAttempts: 3)
        .NotifyOn(JobEvent.Failed | JobEvent.TimedOut);

    // Optional: in-memory history, DLQ, distributed lock
    jobs.WithInMemoryHistory(capacity: 200)
        .WithInMemoryDlq()
        .WithDistributedLock<MyRedisLock>()
        .OnFailure<SlackNotifier>();  // global fallback notifier
});

Implementing a job

public sealed class InvoiceProcessorJob(IInvoiceService invoices) : IArknJob
{
    public async Task<Result> ExecuteAsync(ArknJobContext ctx)
    {
        ctx.Log("Starting invoice processing batch");

        var result = await invoices.ProcessPendingAsync(ctx.CancellationToken);

        return result.Match(
            onSuccess: count => { ctx.Log($"Processed {count} invoices"); return Result.Success(); },
            onFailure: error => Result.Failure(error));
    }
}

Persistence — IJobHistoryStore

Stores job execution records externally (database, blob, etc.). Default is in-memory:

jobs.WithInMemoryHistory(capacity: 100);   // circular buffer, 100 records per job
jobs.WithHistoryStore<MyEfCoreHistoryStore>(); // custom implementation

Query via IJobHistoryStore.GetRecentAsync(jobName, limit) or the scheduler:

app.MapGet("/jobs/history", (IArknJobScheduler scheduler) =>
    Results.Ok(scheduler.GetAllHistory()));

Distributed Lock — IDistributedJobLock

Prevents concurrent execution across multiple instances. Default (NoOpDistributedJobLock) always acquires — suitable for single-instance deployments:

jobs.WithDistributedLock<RedisDistributedJobLock>(); // plug any IDistributedJobLock impl

public sealed class RedisDistributedJobLock(IConnectionMultiplexer redis) : IDistributedJobLock
{
    public async Task<bool> TryAcquireAsync(string jobName, TimeSpan expiry, CancellationToken ct)
        => await redis.GetDatabase().LockTakeAsync(jobName, Environment.MachineName, expiry);

    public async Task ReleaseAsync(string jobName, CancellationToken ct)
        => await redis.GetDatabase().LockReleaseAsync(jobName, Environment.MachineName);
}

Dead-Letter Queue — IJobDlq

Jobs that exhaust all retry attempts are enqueued in the DLQ. Default is in-memory:

jobs.WithInMemoryDlq();

Inspect and drain the DLQ:

app.MapGet("/jobs/dlq", (InMemoryJobDlq dlq) =>
    dlq.GetEntriesAsync());

app.MapDelete("/jobs/dlq/{jobName}", (string jobName, InMemoryJobDlq dlq) =>
    dlq.ClearAsync(jobName));

Cron expression support

Part of the Arkn ecosystem

github.com/fernando-terra/arkn · nuget.org/packages/Arkn.Jobs