Japs.Core 0.6.0

JustAnotherPersistentScheduler (JAPS)

A lightweight, persistent task scheduler for .NET applications with support for multiple storage backends.

Features

• 🚀 Persistent task scheduling - Tasks survive application restarts
• 🔄 Multiple execution attempts - Configurable retry mechanism with exponential backoff
• 💾 Multiple storage backends - Memory and SQL Server providers included
• 🎯 Type-safe task definitions - Strongly typed task handlers and parameters
• ⚡ High performance - Optimized for concurrent execution
• 🔒 Race condition safe - Atomic task locking prevents duplicate execution
• 🏗️ Dependency injection ready - Full integration with .NET DI container

Quick Start

1. Install NuGet packages

# Core package
dotnet add package Japs.Core

# SQL Server provider (optional)
dotnet add package Japs.Core.SqlServer

2. Register services

// Program.cs
builder.Services
    .AddJaps()  // Core services
    .AddJapsSqlServer(new JapsSqlServerConfiguration 
    {
        ConnectionString = "your-connection-string"
    });

// Or use memory storage for development
builder.Services
    .AddJaps()  // Core services only (uses memory storage)

3. Create a task handler

public class SendEmailTask
{
    public string To { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

public class SendEmailHandler : ISchedulerTaskHandler<SendEmailTask>
{
    private readonly IEmailService _emailService;
    
    public SendEmailHandler(IEmailService emailService)
    {
        _emailService = emailService;
    }
    
    public async Task Handle(ScheduledTask scheduledTask, SendEmailTask parameter)
    {
        await _emailService.SendAsync(parameter.To, parameter.Subject, parameter.Body);
    }
}

4. Schedule tasks

public class OrderController : ControllerBase
{
    private readonly IScheduler _scheduler;
    
    public OrderController(IScheduler scheduler)
    {
        _scheduler = scheduler;
    }
    
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        // Process order...
        
        // Schedule confirmation email to be sent in 5 minutes
        await _scheduler.Add(
            SchedulerTaskFactory.From<SendEmailHandler, SendEmailTask>(
                taskKey: $"order-confirmation-{orderId}",
                executeAt: DateTime.UtcNow.AddMinutes(5),
                parameter: new SendEmailTask
                {
                    To = request.Email,
                    Subject = "Order Confirmation",
                    Body = $"Your order #{orderId} has been confirmed"
                }
            ));
            
        return Ok();
    }
}

5. Start the background service

// Program.cs
builder.Services.AddHostedService<SchedulerBackgroundService>();

Advanced Usage

Task Creation Methods

// 1. Basic scheduling
await scheduler.Add(SchedulerTaskFactory.From<Handler, Parameter>(
    "task-key", executeAt, parameter));

// 2. With group key for batch operations
await scheduler.Add(SchedulerTaskFactory.From<Handler, Parameter>(
    "task-key", "group-key", executeAt, parameter));

// 3. With retry configuration
await scheduler.Add(SchedulerTaskFactory.From<Handler, Parameter>(
    "task-key", executeAt, parameter, retryCount: 5));

// 4. Immediate execution
await scheduler.Add(SchedulerTaskFactory.FromNow<Handler, Parameter>(
    "task-key", parameter));

// 5. Delayed execution
await scheduler.Add(SchedulerTaskFactory.FromDelay<Handler, Parameter>(
    "task-key", TimeSpan.FromHours(1), parameter));

Task Management

// Remove specific task
await scheduler.RemoveByTaskKey("task-key");

// Remove all tasks in a group
await scheduler.RemoveByGroupKey("group-key");

// Remove by unique identifier
await scheduler.RemoveByPK(taskId);

Error Handling

Tasks that throw exceptions are automatically retried based on the configured retry count. Failed tasks are logged with full error details including stack traces.

public async Task Handle(ScheduledTask scheduledTask, MyTask parameter)
{
    try
    {
        // Your task logic here
        await ProcessTask(parameter);
    }
    catch (TemporaryException ex)
    {
        // This will trigger a retry (if retries remaining)
        throw;
    }
    catch (PermanentException ex)
    {
        // Log and don't retry
        _logger.LogError(ex, "Permanent failure processing task");
        return; // Don't throw - task will be marked as completed
    }
}

Configuration

SQL Server Provider

services.AddJapsSqlServer(new JapsSqlServerConfiguration
{
    ConnectionString = "Server=...;Database=...;",
    TableName = "ScheduledTasks" // Optional, default: "ScheduledTasks"
});

Background Service Options

services.Configure<JapsConfiguration>(options =>
{
    options.CheckIntervalInMilliseconds = 5000; // Default: 5 seconds
});

Architecture

JAPS uses a race-condition-free approach to task execution:

1. GetTasksIds() - Quickly retrieves IDs of tasks ready for execution
2. GetAndLockTask() - Atomically locks and retrieves individual tasks
3. Parallel processing - Multiple scheduler instances can run safely

This design ensures that each task is executed exactly once, even in multi-instance deployments.

Requirements

• .NET 6.0 or later
• SQL Server (when using SqlServer provider)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.