Akka.Reminders 1.5.75

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Akka.Reminders --version 1.5.75
                    
NuGet\Install-Package Akka.Reminders -Version 1.5.75
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Akka.Reminders" Version="1.5.75" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Akka.Reminders" Version="1.5.75" />
                    
Directory.Packages.props
<PackageReference Include="Akka.Reminders" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Akka.Reminders --version 1.5.75
                    
#r "nuget: Akka.Reminders, 1.5.75"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Akka.Reminders@1.5.75
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Akka.Reminders&version=1.5.75
                    
Install as a Cake Addin
#tool nuget:?package=Akka.Reminders&version=1.5.75
                    
Install as a Cake Tool

Akka.Reminders

Durable, re-entrant reminders system for Akka.Cluster.Sharding - designed for scheduling and delivering time-based messages to sharded entities with automatic persistence and recovery.

Overview

Akka.Reminders provides a reliable way to schedule reminders (time-delayed messages) for your sharded actors. Unlike standard Akka.NET scheduling, reminders are:

  • Durable: Persisted to storage and survive actor restarts
  • Re-entrant: Automatically rescheduled after delivery
  • Cluster-aware: Run as a cluster singleton with proper failover
  • Scalable: Handle thousands of reminders with minimal overhead

Features

  • ✅ Single and recurring reminders - Schedule one-time or repeating time-based messages
  • ✅ SQL storage backends - Production-ready SQL Server, PostgreSQL, and SQLite support
  • ✅ Automatic retries - Failed deliveries retry with exponential backoff
  • ✅ Cluster singleton - Reminder scheduler with automatic failover
  • ✅ Akka.Hosting integration - First-class configuration API
  • ✅ Testable - Uses ITimeProvider abstraction for deterministic testing
  • ✅ Automatic cleanup - Periodic pruning of completed/cancelled reminders
  • ✅ Delivery tracking - Monitor attempts, failures, and completion status

Table of Contents

Installation

Core Package:

dotnet add package Akka.Reminders

SQL Server Storage:

dotnet add package Akka.Reminders.SqlServer

PostgreSQL Storage:

dotnet add package Akka.Reminders.PostgreSql

SQLite Storage:

dotnet add package Akka.Reminders.Sqlite

Legacy Compatibility Package (all providers):

dotnet add package Akka.Reminders.Sql

Supported Storage Backends

Storage Backend Package Auto-Initialize Documentation
In-Memory Akka.Reminders N/A Built-in (development/testing only)
SQL Server Akka.Reminders.SqlServer Yes SQL Server Schema
PostgreSQL Akka.Reminders.PostgreSql Yes PostgreSQL Schema
SQLite Akka.Reminders.Sqlite Yes SQLite Schema

Compatibility: Akka.Reminders.Sql remains available and fully functional as a compatibility package, but new projects should prefer provider-specific packages (SqlServer, PostgreSql, or Sqlite).

Note: For production deployments, you can manually create database schemas using the provided SQL scripts instead of using auto-initialization.

Quick Start

Basic Setup with In-Memory Storage

using Akka.Hosting;
using Akka.Reminders;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAkka("MySystem", (configBuilder, provider) =>
{
    configBuilder
        .WithClustering()
        .WithShardRegion<MyEntity>(
            "my-entities",
            (system, registry, resolver) => entityId =>
                Props.Create(() => new MyEntityActor(entityId)),
            new MyMessageExtractor(),
            new ShardOptions())
        .WithReminders("reminder-host", reminders => reminders
            .WithStorage(_ => new InMemoryReminderStorage()));
});

Production Setup with SQL Server

using Akka.Hosting;
using Akka.Reminders;
using Akka.Reminders.SqlServer.Hosting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAkka("MySystem", (configBuilder, provider) =>
{
    configBuilder
        .WithClustering()
        .WithShardRegion<MyEntity>(
            "my-entities",
            (system, registry, resolver) => entityId =>
                Props.Create(() => new MyEntityActor(entityId)),
            new MyMessageExtractor(),
            new ShardOptions())
        .WithReminders("reminder-host", reminders => reminders
            .WithSqlServerStorage(
                connectionString: builder.Configuration.GetConnectionString("Reminders"),
                schemaName: "dbo",
                tableName: "akka_reminders",
                autoInitialize: true));
});

Using Reminders in Actors

public class MyEntityActor : ReceiveActor
{
    private readonly IReminderClient _reminders;

    public MyEntityActor(string entityId)
    {
        var extension = Context.System.ReminderClient();
        _reminders = extension.CreateClient("my-entities", entityId);

        ReceiveAsync<ScheduleReminder>(async msg =>
        {
            // Schedule a one-time reminder that expires if it is more than 30 seconds late.
            var result = await _reminders.ScheduleSingleReminderAsync(
                new ReminderKey("my-reminder"),
                DateTimeOffset.UtcNow.AddMinutes(5),
                new DoSomething(),
                maxDeliveryWindow: TimeSpan.FromSeconds(30));

            if (result.ResponseCode == ReminderScheduleResponseCode.Success)
            {
                // Reminder scheduled successfully
            }
        });

        ReceiveAsync<ScheduleRecurring>(async msg =>
        {
            // Schedule a recurring reminder that fires every hour
            await _reminders.ScheduleRecurringReminderAsync(
                new ReminderKey("hourly-check"),
                DateTimeOffset.UtcNow.AddHours(1),
                TimeSpan.FromHours(1),
                new PerformHealthCheck());
        });

        ReceiveAsync<ReminderEnvelope<DoSomething>>(async envelope =>
        {
            if (envelope.Deadline.IsExpired())
            {
                await _reminders.AckAsync(envelope);
                return;
            }

            // Handle the reminder when it fires
            Console.WriteLine("Reminder received!");

            // Acknowledge receipt so the scheduler marks it delivered.
            // If AckAsync fails or times out, the reminder will be retried.
            await _reminders.AckAsync(envelope);
        });
    }
}

Configuration

SQL Server Storage

using Akka.Reminders.SqlServer.Hosting; using Akka.Reminders.SqlServer.Configuration;

The WithSqlServerStorage extension method configures SQL Server as the reminder storage backend:

.WithReminders("reminder-host", reminders => reminders
    .WithSqlServerStorage(
        connectionString: "Server=localhost;Database=Reminders;User Id=sa;Password=YourPassword;",
        schemaName: "dbo",
        tableName: "akka_reminders",
        autoInitialize: true))

Parameters:

  • connectionString: SQL Server connection string
  • schemaName: Database schema name (default: "reminders")
  • tableName: Table name for reminders (default: "scheduled_reminders")
  • autoInitialize: Auto-create schema/table if missing (default: true)

Advanced Configuration:

.WithReminders("reminder-host", reminders => reminders
    .WithSqlServerStorage(new SqlServerReminderStorageSettings
    {
        ConnectionString = "Server=localhost;...",
        SchemaName = "custom_schema",
        TableName = "my_reminders",
        CommandTimeout = TimeSpan.FromSeconds(60),
        AutoInitialize = false // Manual schema management
    }))

Connection Factory (Azure AD access tokens):

When a connection needs settings a connection string can't carry, such as an Azure AD access token, pass a connection factory instead of a connection string:

.WithReminders("reminder-host", reminders => reminders
    .WithSqlServerStorage(
        connectionFactory: async ct => new SqlConnection(connectionString)
        {
            AccessToken = await tokenProvider.GetTokenAsync(ct)
        },
        autoInitialize: true))

The factory must return a new, unopened connection. The storage opens and disposes it, and calls the factory once per operation (schema auto-initialization included), so each call can return a fresh token. The overload takes the same optional schemaName, tableName and autoInitialize parameters. You can also set SqlServerReminderStorageSettings.ConnectionFactory; set exactly one of ConnectionString or ConnectionFactory, or Validate() throws. No process-wide SqlAuthenticationProvider is needed.

Manual Schema Setup:

For production environments, you may prefer to manually create the database schema. Use the provided SQL script:

📄 SQL Server Schema Script

-- Run this script against your database
-- Creates schema, table, and indexes

PostgreSQL Storage

using Akka.Reminders.PostgreSql.Hosting; using Akka.Reminders.PostgreSql.Configuration;

The WithPostgreSqlStorage extension method configures PostgreSQL as the reminder storage backend:

.WithReminders("reminder-host", reminders => reminders
    .WithPostgreSqlStorage(
        connectionString: "Host=localhost;Database=reminders;Username=postgres;Password=postgres",
        schemaName: "public",
        tableName: "akka_reminders",
        autoInitialize: true))

Parameters:

  • connectionString: PostgreSQL connection string
  • schemaName: Database schema name (default: "reminders")
  • tableName: Table name for reminders (default: "scheduled_reminders")
  • autoInitialize: Auto-create schema/table if missing (default: true)

Backward compatibility: default schema remains reminders unless you explicitly override it.

Advanced Configuration:

.WithReminders("reminder-host", reminders => reminders
    .WithPostgreSqlStorage(new PostgreSqlReminderStorageSettings
    {
        ConnectionString = "Host=localhost;...",
        SchemaName = "custom_schema",
        TableName = "my_reminders",
        CommandTimeout = TimeSpan.FromSeconds(60),
        AutoInitialize = false // Manual schema management
    }))

Manual Schema Setup:

For production environments, you may prefer to manually create the database schema. Use the provided SQL script:

📄 PostgreSQL Schema Script

-- Run this script against your database
-- Creates schema, table, and indexes

HOCON Configuration:

akka.reminders.postgresql {
  connection-string = "Host=localhost;Database=reminders;Username=postgres;Password=postgres"
  schema-name = "public"
  table-name = "scheduled_reminders"
  auto-initialize = true
  command-timeout = 30s
}
.WithReminders("reminder-host", reminders => reminders
    .WithPostgreSqlStorageFromConfig())

SQLite Storage

using Akka.Reminders.Sqlite.Hosting;

The WithSqliteStorage extension method configures SQLite as the reminder storage backend:

.WithReminders("reminder-host", reminders => reminders
    .WithSqliteStorage(
        connectionString: "Data Source=reminders.db;Mode=ReadWriteCreate;Cache=Shared",
        tableName: "akka_reminders",
        autoInitialize: true))

Parameters:

  • connectionString: SQLite connection string
  • tableName: Table name for reminders (default: "scheduled_reminders")
  • autoInitialize: Auto-create table if missing (default: true)

Manual Schema Setup:

📄 SQLite Schema Script

In-Memory Storage

For development and testing, use the built-in in-memory storage:

// Explicit convenience method (recommended)
.WithReminders("reminder-host", reminders => reminders
    .WithInMemoryStorage())

// Or manually instantiate
.WithReminders("reminder-host", reminders => reminders
    .WithStorage(_ => new InMemoryReminderStorage()))

⚠️ Warning: In-memory storage is not durable and should only be used for development/testing.

💡 Tip: For unit tests, consider using WithLocalReminders() instead for instant startup without cluster bootstrap delays. See the Testing section for details.

Reminder Settings

Configure reminder behavior and performance characteristics:

.WithReminders("reminder-host", reminders => reminders
    .WithSqlServerStorage(connectionString: "...")
    .WithSettings(new ReminderSettings
    {
        // Maximum time drift allowed before immediate delivery
        MaxSlippage = TimeSpan.FromSeconds(5),

        // Timeout for storage operations
        StorageTimeout = TimeSpan.FromSeconds(5),

        // How frequently to prune completed/cancelled reminders
        PruneInterval = TimeSpan.FromHours(12),

        // Age threshold for pruning reminders
        PruneOlderThan = TimeSpan.FromDays(30),

        // Maximum delivery attempts before marking as permanently failed
        // Applies to both infrastructure failures and ack timeouts
        MaxDeliveryAttempts = 10,

        // Default window an occurrence stays actionable after its due time.
        // null (default) = no deadline: retries continue until MaxDeliveryAttempts.
        // Strongly recommended to set this so stale reminders expire instead of replaying.
        DefaultMaxDeliveryWindow = TimeSpan.FromHours(24),

        // Maximum reminders fetched per batch (limits query size under load)
        MaxBatchSize = 1000,

        // Maximum reminders delivered before writes are attempted.
        // Lower values reduce duplicate blast radius during write outages.
        DeliveryCommitChunkSize = 100,

        // Base delay for exponential backoff on retries
        // Retries are also bounded by each occurrence's delivery deadline.
        RetryBackoffBase = TimeSpan.FromSeconds(60),

        // Cap on exponential backoff to prevent absurdly long intervals
        MaxRetryBackoff = TimeSpan.FromMinutes(10),

        // How long to wait for a recipient ack before retrying delivery.
        // This also controls the Deadline on delivered ReminderEnvelope<T> messages —
        // when another retry is possible, the envelope deadline equals the ack timeout
        // so recipients know exactly how long until the next delivery replaces this one.
        AckTimeout = TimeSpan.FromSeconds(10)
    }))

⚠️ Warning: By default a reminder has no delivery deadline — it is retried until MaxDeliveryAttempts is exhausted, no matter how far past its due time it drifts. After a restart, upgrade, or prolonged outage this can cause a large backlog of stale reminders to fire at once. Set DefaultMaxDeliveryWindow (or pass maxDeliveryWindow per call) to how long a reminder stays actionable after its due time — for example 24 hours — so overdue occurrences expire instead of replaying.

Usage Examples

Health Check Pattern

public class HealthCheckActor : ReceiveActor
{
    private readonly IReminderClient _reminders;

    public HealthCheckActor(string entityId)
    {
        _reminders = Context.System.ReminderClient()
            .CreateClient("health-checks", entityId);

        ReceiveAsync<Initialize>(async _ =>
        {
            // Schedule health check every 5 minutes
            await _reminders.ScheduleRecurringReminderAsync(
                new ReminderKey("health-check"),
                DateTimeOffset.UtcNow.AddMinutes(5),
                TimeSpan.FromMinutes(5),
                new PerformHealthCheck());
        });

        ReceiveAsync<ReminderEnvelope<PerformHealthCheck>>(async envelope =>
        {
            if (envelope.Deadline.IsExpired())
            {
                await _reminders.AckAsync(envelope);
                return;
            }

            var isHealthy = await CheckHealth();
            if (!isHealthy)
            {
                Self.Tell(new Restart());
            }

            await _reminders.AckAsync(envelope);
        });
    }
}

Delayed Order Processing

public class OrderActor : ReceiveActor
{
    private readonly IReminderClient _reminders;

    public OrderActor(string orderId)
    {
        _reminders = Context.System.ReminderClient()
            .CreateClient("orders", orderId);

        ReceiveAsync<PlaceOrder>(async order =>
        {
            await ProcessOrder(order);

            // Schedule payment check in 24 hours
            await _reminders.ScheduleSingleReminderAsync(
                new ReminderKey("payment-check"),
                DateTimeOffset.UtcNow.AddHours(24),
                new CheckPayment());
        });

        ReceiveAsync<ReminderEnvelope<CheckPayment>>(async envelope =>
        {
            if (envelope.Deadline.IsExpired())
            {
                await _reminders.AckAsync(envelope);
                return;
            }

            if (!await PaymentReceived())
            {
                Self.Tell(new CancelOrder());
            }

            await _reminders.AckAsync(envelope);
        });
    }
}

API Reference

IReminderClient

The IReminderClient interface provides the primary API for scheduling and managing reminders:

// Get client instance for an entity
var extension = Context.System.ReminderClient();
var client = extension.CreateClient("shard-region-name", "entity-id");
Schedule Single Reminder
Task<ReminderScheduled> ScheduleSingleReminderAsync(
    ReminderKey key,
    DateTimeOffset when,
    object message,
    TimeSpan? maxDeliveryWindow = null,
    CancellationToken cancellationToken = default)

Schedules a one-time reminder that fires at the specified time. When maxDeliveryWindow is provided, the occurrence expires after when + maxDeliveryWindow and will not be retried beyond that deadline.

Schedule Recurring Reminder
Task<ReminderScheduled> ScheduleRecurringReminderAsync(
    ReminderKey key,
    DateTimeOffset firstOccurrence,
    TimeSpan interval,
    object message,
    TimeSpan? maxDeliveryWindow = null,
    CancellationToken cancellationToken = default)

Schedules a recurring reminder that fires repeatedly at the specified interval. Recurring reminders are latest-only: each occurrence expires when a later occurrence is delivered or the next one becomes due, or sooner if maxDeliveryWindow produces an earlier deadline.

Cancel Reminder
Task<ReminderCancelled> CancelReminderAsync(
    ReminderKey key,
    CancellationToken cancellationToken = default)

Cancels a specific reminder by key.

Cancel All Reminders
Task<RemindersCancelled> CancelAllRemindersAsync(
    CancellationToken cancellationToken = default)

Cancels all reminders for the current entity.

List Reminders
Task<FetchedReminders> ListRemindersAsync(
    CancellationToken cancellationToken = default)

Lists all active reminders for the current entity.

Acknowledge Reminder
Task<ReminderAckResponse> AckAsync(
    ReminderEnvelope envelope,
    CancellationToken cancellationToken = default)

Acknowledges receipt of a delivered reminder. Must be called after processing a ReminderEnvelope<T>. If this call faults or times out, the scheduler will redeliver the reminder after AckTimeout elapses, subject to the occurrence deadline.

Reject Reminder
var nack = await client.NackAsync(envelope, "Downstream service was unavailable");
if (nack.ResponseCode == ReminderNackResponseCode.RetryScheduled)
{
    Log.Info("Retry {0} is scheduled for {1}", nack.AttemptCount, nack.NextAttemptAtUtc);
}

NackAsync uses the current retry budget, deadline, and exponential backoff. It returns Failed or Expired when the occurrence cannot retry.

Get Occurrence Status
var status = await client.GetOccurrenceStatusAsync(
    envelope.Key,
    envelope.DueTimeUtc);

The status query returns terminal rows until normal pruning removes them. Official storage providers support status queries without a schema migration.

For 0.7 recurring reminders, custom storage providers must implement IConditionalReminderMutationStorage and honor the insert-only successors and active-only completions in ReminderMutationBatch atomically. Existing IReminderStorage providers continue to support one-off reminders. See the storage contract.

The new delivery-control messages use new serializer manifests. Upgrade the reminder scheduler before a consumer calls this API. A 0.6 scheduler cannot read the 0.7 negative acknowledgement or status messages. Custom providers must implement the new IReminderStorage query operations.

MaxDeliveryAttempts applies to one occurrence. A recurring reminder creates a new occurrence with a new retry budget. A failed occurrence does not disable the recurring reminder.

Acknowledgement Protocol

Reminders are wrapped in ReminderEnvelope<T> before delivery. The envelope carries the original payload alongside the ReminderEntity, ReminderKey, occurrence DueTimeUtc, and a non-null Deadline value object.

The Deadline tells the recipient how long the current delivery is relevant:

  • When another retry is possible (attempts remain and the next backoff fits within the occurrence deadline): the deadline equals the ack timeout for this attempt (now + AckTimeout). A new delivery will replace this one when the deadline passes.
  • When this is the final attempt (max attempts reached, or backoff would exceed the occurrence deadline): the deadline equals the occurrence-level delivery deadline.
  • When there is no occurrence deadline and no more retries: the deadline is ReminderDeadline.Infinite.

Use envelope.Deadline.TimeRemaining() to know how long you have, or envelope.Deadline.IsExpired() to check whether a new delivery has likely already replaced this one.

Receiving and acknowledging a reminder:

ReceiveAsync<ReminderEnvelope<DoSomething>>(async envelope =>
{
    // Drop stale work before doing side effects.
    if (envelope.Deadline.IsExpired())
    {
        await _reminders.AckAsync(envelope);
        return;
    }

    // Process the reminder payload first (idempotently).
    // Use DueTimeUtc as your occurrence identity for dedupe.
    await DoWork(envelope.Message);

    // Then acknowledge. If this fails, the reminder is retried.
    var ack = await _reminders.AckAsync(envelope);
    if (ack.ResponseCode != ReminderAckResponseCode.Success)
    {
        // Log the failure; the scheduler will retry after AckTimeout
        Log.Warning("Ack failed: {0}", ack.Message);
    }
});

What happens on each outcome:

Outcome Scheduler behavior
AckAsync succeeds Current occurrence marked Delivered
NackAsync succeeds Current attempt fails and the normal retry policy runs immediately
AckAsync times out or returns Error Reminder retried after AckTimeout (default: 10s) with exponential backoff while it is still before the occurrence deadline
Retry attempts exhausted (MaxDeliveryAttempts) Reminder marked Failed
Reminder exceeds its deadline Reminder marked Expired and will not be retried
Ack received for a stale or superseded occurrence Scheduler returns NotFound; the ack is a harmless no-op

Because duplicates are possible whenever an ack is lost or times out, consumers must be idempotent. For recurring reminders, dedupe by (ReminderEntity, ReminderKey, DueTimeUtc).

Response Codes

ReminderScheduleResponseCode:

  • Success: Reminder scheduled successfully
  • ShardRegionNotFound: Target shard region doesn't exist
  • Error: Unexpected error occurred

ReminderCancelResponseCode:

  • Success: Reminder(s) cancelled successfully
  • NotFound: Reminder not found
  • Error: Unexpected error occurred

Reminder States

Reminders progress through the following states:

  • Pending: Scheduled but not yet delivered
  • AwaitingAck: Delivered via Tell; waiting for recipient to call AckAsync
  • Delivered: Recipient acknowledged the occurrence
  • Failed: Permanently failed after MaxDeliveryAttempts exhausted
  • Expired: Deadline passed before the occurrence could be successfully acknowledged
  • Cancelled: Manually cancelled by user

Testing

Local Reminders for Fast Testing

For unit and integration tests, use WithLocalReminders() to avoid the 30+ second ClusterSingleton bootstrap delay:

using Akka.Hosting;
using Akka.Reminders;

public class ReminderTests : Akka.Hosting.TestKit.TestKit
{
    private readonly TestShardRegionResolver _resolver = new();

    protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
    {
        // Configure local reminders - starts instantly without cluster
        builder.WithLocalReminders(reminders => reminders
            .WithInMemoryStorage()
            .WithResolver(_resolver)
            .WithSettings(new ReminderSettings
            {
                MaxSlippage = TimeSpan.FromMilliseconds(100),
                MaxDeliveryAttempts = 3
            }));
    }

    [Fact]
    public async Task Reminder_ShouldDeliver_ToRegisteredShardRegion()
    {
        // Arrange
        var targetActor = CreateTestProbe("billing-actor");
        _resolver.RegisterShardRegion("billing-shard", targetActor);

        var client = Sys.ReminderClient().CreateClient("billing-shard", "customer-123");

        // Act - Schedule reminder
        await client.ScheduleSingleReminderAsync(
            new ReminderKey("retry-payment"),
            DateTimeOffset.UtcNow.AddMilliseconds(200),
            new PaymentRetry());

        // Assert - Reminder delivered wrapped in ReminderEnvelope
        var shardEnvelope = targetActor.ExpectMsg<ShardingEnvelope>(TimeSpan.FromSeconds(2));
        Assert.Equal("customer-123", shardEnvelope.EntityId);
        var reminderEnvelope = Assert.IsType<ReminderEnvelope<PaymentRetry>>(shardEnvelope.Message);
    }
}

Key Differences:

Feature WithReminders() (Production) WithLocalReminders() (Testing)
Startup Time 30+ seconds (ClusterSingleton bootstrap) Instant (regular actor)
Clustering Required Not required
Shard Resolver Uses real ClusterSharding Manual registration via TestShardRegionResolver
Storage Configurable (SQL, in-memory) Defaults to in-memory
Use Case Production deployments Unit/integration tests

Why Use Local Reminders?

  • ✅ No Cluster Bootstrap Delay: Tests start instantly
  • ✅ Simple Setup: Register test probes as shard regions
  • ✅ Full Functionality: All reminder features work in local mode
  • ✅ Better Test Isolation: No shared cluster state between tests

Time-Based Testing with TestScheduler

Akka.Reminders uses the ITimeProvider abstraction (mapped to IScheduler) for time operations, making it fully testable with TestScheduler:

[Fact]
public async Task Reminder_should_fire_at_scheduled_time()
{
    // Arrange
    var testScheduler = new TestScheduler();
    var system = ActorSystem.Create("test", config);

    // Schedule reminder
    var reminderTime = testScheduler.Now.AddMinutes(5);
    await client.ScheduleSingleReminderAsync(
        new ReminderKey("test"),
        reminderTime,
        new TestMessage());

    // Act - Advance time
    testScheduler.Advance(TimeSpan.FromMinutes(5));

    // Assert - Reminder fires (wrapped in ReminderEnvelope)
    testProbe.ExpectMsg<ReminderEnvelope<TestMessage>>();
}

Native AOT

Local mode (WithLocalReminders) works under .NET Native AOT. All five packages are marked IsAotCompatible and produce no trim or AOT warnings of their own. The repository's AOT canary (src/aot/Akka.Reminders.AOT.App) has an independent Native AOT canary (linux-x64) CI job: it publishes with PublishAot, schedules, delivers and acks reminders with in-memory and SQLite storage, and restarts to deliver a reminder restored from the SQLite file.

Clustered mode (WithReminders, which runs the scheduler as a cluster singleton and delivers through Cluster.Sharding) is not supported under Native AOT yet, because Akka.Cluster itself is not AOT-ready in Akka.NET 1.6.

Start with the Akka.NET v1.6 getting started guide, also linked from Akka.NET's 1.6 release notes. Its Native AOT and source-generated serializer sections explain the runtime and serialization setup.

Register your message types

The scheduler delivers each reminder as a ReminderEnvelope<T>, where T is the runtime type of the message. On the JIT it builds that type by reflection. Native AOT cannot, so register every message type you schedule:

builder
    .WithCustomSerializer("billing", [typeof(PaymentRetry)], system => new BillingSerializer(system))
    .WithLocalReminders(reminders => reminders
        .WithReminderMessage<PaymentRetry>()
        .WithStorage(system => new SqliteReminderStorage(
            SqliteReminderStorageSettings.Create("Data Source=reminders.db"), system))
        .WithResolver(_ => resolver));
  • Register the exact runtime type. A registration for a base type does not cover subclasses.
  • This also covers reminders restored from storage after a restart, which no code in the new process ever scheduled.
  • If a type is not registered, ScheduleSingleReminderAsync and ScheduleRecurringReminderAsync return ReminderScheduleResponseCode.Error with a message that names the type and the WithReminderMessage<T>() call, and nothing is stored. A stored reminder whose type is not registered logs an error at delivery and follows the normal ack-timeout retry path.
  • On the JIT, registration is optional and changes nothing: unregistered types still go through reflection.
  • Outside Akka.Hosting, call ReminderMessageTypes.Register<PaymentRetry>() at startup. Registration is process-wide and safe to repeat.

Use an AOT-compatible payload serializer

Akka.NET turns its Akka.DynamicTypeLoading feature switch off for AOT publishes. Reflection-based serializers do not work under Native AOT, including Akka.NET's default Newtonsoft.Json fallback, which is unavailable with the switch off. SQL storage serializes each reminder's payload through Akka.NET serialization; in-memory storage does not serialize payloads.

For durable storage, use one of these options:

  • Akka.NET 1.6's source-generated serializer in Akka.Serialization.V2, which generates MessagePack serialization code at compile time.
  • An AOT-compatible built-in Akka.NET serializer, where it supports your payload type.
  • An AOT-compatible custom serializer, registered with WithCustomSerializer as in the example above. For example, a SerializerWithStringManifest implementation can map stable manifest strings to generated Protobuf parsers explicitly.

Using SerializerWithStringManifest or Protobuf alone is not sufficient: the implementation must avoid runtime type discovery and code generation. Resolve manifests explicitly instead of relying on Type.GetType to reconstruct a payload type.

WithReminderMessage<T>() only registers the ReminderEnvelope<T> factory. It does not register a payload serializer or change the serializer ID, manifest, or bytes of existing stored reminders.

Check existing stored reminders before switching to Native AOT. The 1.5-to-1.6 read compatibility applies to the ordinary JIT runtime with dynamic type loading enabled. Old rows written through the JSON fallback are not automatically readable under AOT. Provide an AOT-compatible reader for their existing serializer IDs, manifests, and payload format, or migrate them before switching the store to Native AOT. Registering a different serializer for future writes does not migrate old rows.

To test this behavior on the JIT before you publish, turn the switch off in your project file:

<ItemGroup>
  <RuntimeHostConfigurationOption Include="Akka.DynamicTypeLoading" Value="false" Trim="true" />
</ItemGroup>

Environment notes

  • SQL Server: Microsoft.Data.SqlClient needs <InvariantGlobalization>false</InvariantGlobalization> under Native AOT.
  • Expected warnings: an AOT publish reports about 70 trim/AOT warnings from Akka.Remote, Akka.Cluster, Akka.DistributedData and Akka.Persistence. They appear because this package references Akka.Cluster.Hosting; local mode does not reach that code. src/aot/Akka.Reminders.AOT.App/aot-warnings.baseline.txt lists them.

Architecture

Components

  • ReminderScheduler: Cluster singleton actor that manages reminder scheduling and delivery
  • ReminderClient: Client API for scheduling and managing reminders
  • ReminderClientExtension: ActorSystem extension for accessing the reminder system
  • IReminderStorage: Pluggable storage abstraction for persistence backends
  • IShardRegionResolver: Resolves shard region names to actor references

Message Flow

  1. Entity actor requests reminder via IReminderClient
  2. Request routed to ReminderScheduler singleton (via cluster singleton proxy)
  3. Reminder persisted to storage backend
  4. Scheduler tracks next due reminder time
  5. When due, the scheduler persists the occurrence's delivery state (and any next recurring occurrence) before sending
  6. Message wrapped in ReminderEnvelope<T> and delivered to the target shard region via Tell
  7. Recipient calls IReminderClient.AckAsync(envelope) to confirm receipt for that specific DueTimeUtc
  8. If ack times out: delivery retried with exponential backoff while the occurrence remains before deadline
  9. Recurring reminders are latest-only; older occurrences expire when a later occurrence is delivered or the next one becomes due
  10. Completed/cancelled/expired reminders are pruned periodically based on PruneInterval setting

Reliability Features

  • At-least-once delivery with acknowledgement: Reminders are wrapped in ReminderEnvelope<T> and delivered via Tell. Recipients call IReminderClient.AckAsync(envelope) to confirm receipt. Unacknowledged reminders are retried with exponential backoff until they expire or exhaust attempts. Consumers must be idempotent.
  • Durable persistence: Reminders survive actor restarts and cluster failures
  • Deadline-bounded retries: Failed deliveries retry with exponential backoff inside each occurrence's absolute delivery deadline
  • Cluster singleton: Single scheduler instance with automatic failover
  • Occurrence identity: Reminders track delivery attempts, deadlines, and due-time identity per occurrence
  • Periodic pruning: Automatic cleanup of old completed/cancelled reminders
  • Write circuit breaker: Automatically pauses batch delivery when database writes fail, probing with a single reminder until writes recover. Prevents duplicate delivery storms during database outages.
  • Bounded first-failure blast radius: Interleaved deliver/persist chunking caps duplicate deliveries on the first failed tick to DeliveryCommitChunkSize.

For a detailed analysis of failure modes and design trade-offs, see Failure Modes and Design Decisions.

Design Documents

Building from Source

# Restore tools
dotnet tool restore

# Build
dotnet build

# Run tests
dotnet test

# Pack NuGet package
dotnet pack -c Release

Contributing

Contributions are welcome! Please ensure:

  • All tests pass
  • Code follows existing style
  • New features include tests
  • Public APIs are documented

License

Apache 2.0 License - see LICENSE file for details.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on Akka.Reminders:

Package Downloads
Aaron.Akka.Durable

Event-sourced durable entities for Akka.NET: describe an entity with Decide and Evolve functions, and Akka.Durable persists, recovers and hosts it locally or in Akka.Cluster.Sharding, with typed entity references, durable reminders and Akka.Hosting integration.

Akka.Reminders.PostgreSql

PostgreSQL storage implementation for Akka.Reminders.

Akka.Reminders.Sqlite

SQLite storage implementation for Akka.Reminders.

Akka.Reminders.Sql

Compatibility package for SQL Server, PostgreSQL, and SQLite storage in Akka.Reminders.

Akka.Reminders.SqlServer

SQL Server storage implementation for Akka.Reminders.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.6.0-beta8 0 11/18/2026
1.5.75 60 11/16/2026

Akka.NET v1.5.75 adds restart-free TLS certificate rotation for the DotNetty transport, fixes two certificate-validation gaps that silently disabled security checks, backports two Akka.Persistence ordering fixes, and brings Akka.Reminders to the 1.5 line as `Akka.Reminders.*` packages.

**Upgrading from `Aaron.Akka.Reminders`?** The package IDs are now `Akka.Reminders`, `Akka.Reminders.Sql`, `Akka.Reminders.SqlServer`, `Akka.Reminders.PostgreSql` and `Akka.Reminders.Sqlite`, and the module shares the Akka.NET version number. Change your package references; stored data is read-compatible, proven by a golden-database spec against data written by the released `Aaron.Akka.Reminders` 1.5.73 packages.

**Two behavior changes to check before upgrading.** `CertificateValidation.ValidateHostname(expectedHostname)` and `SslOptions.CustomValidator` now actually enforce what they were configured to enforce. Both were silently no-ops in earlier versions, so a peer that used to connect may now fail the TLS handshake. See the Akka.Remote / TLS section below.

**Akka.Remote / TLS**
* [Rotate DotNetty TLS certificates without a restart](https://github.com/akkadotnet/akka.net/pull/8960) - A node can now pick up a renewed TLS certificate with no restart. Set `akka.remote.dot-netty.tcp.ssl.certificate.common-name` to find the certificate in a store by name, or point `ssl.certificate.path` at a folder of PKCS#12/PEM files, and place the renewed certificate beside the old one. New connections use it within about 10 seconds; open connections keep the certificate they started with. In code, use `DotNettySslSetup.FromSource` with `TlsCertificateSource`, or `SslOptions.CertificateSource` in Akka.Hosting. Existing TLS setups are unchanged. **Behavior change:** a certificate source checks that the certificate is allowed for the role. With `require-mutual-authentication = true` (the default) the certificate must allow both client and server authentication. `X509Certificate`, a single-file `Path` and a `Thumbprint` are not checked this way, so a certificate that worked before may be skipped with a warning when moved to a source, and a node with no other usable certificate does not start.
* [Add `TlsCertificateSource` for TLS certificate rotation](https://github.com/akkadotnet/akka.net/pull/8959) - The new `Akka.IO.TlsCertificateSource` resolves a certificate from a store common name, a thumbprint, a single file, or a folder of files, and re-checks it once a minute. A certificate that cannot be used is judged again at the next look-up, so granting access to a private key later is picked up. The source never disposes a certificate it has published. PEM files need the `net6.0` target; the `netstandard2.0` build skips them and logs why.
* [Security fix: `CertificateValidation.ValidateHostname(expectedHostname)` now enforces the expected hostname](https://github.com/akkadotnet/akka.net/pull/8958) - In v1.5.74 and earlier this validator logged a warning and did not compare `expectedHostname` with the certificate, so a node that used it to check inbound client certificates accepted every client certificate. It now rejects any certificate that does not match the name, by the rules of .NET's `X509Certificate2.MatchesHostname`. **Behavior change:** a certificate that does not match now fails the TLS handshake, and on the dialing side that shuts the `ActorSystem` down with exit code 79. Only nodes that opt in are affected: `validate-certificate-hostname` defaults to `false`. A certificate whose subject alternative name extension holds a malformed entry is rejected, as in 1.6. `ValidateHostname()` without an argument is unchanged.
* [Security fix: `SslOptions.CustomValidator` in Akka.Remote.Hosting now applies when the certificate is set by file path or thumbprint](https://github.com/akkadotnet/akka.net/pull/8963) - In earlier versions the validator only ran when `SslOptions.X509Certificate` was set, and was otherwise ignored without a warning. **Behavior change:** the validator now runs, so a peer it rejects fails the TLS handshake. A `CustomValidator` with no certificate in the options now fails at startup with a `ConfigurationException`, and the certificate loads when `WithRemoting` runs rather than when the `ActorSystem` starts.
* [Log an unexpected failure of the once-a-minute TLS certificate check](https://github.com/akkadotnet/akka.net/pull/8972) - The check's catch block swallowed any unexpected exception without a trace. The source already logs every failure it expects, so anything reaching this catch is a bug, and it now logs a warning. The node keeps its current certificate, as before.

**Akka.Reminders**
* [Port Akka.Reminders to v1.5](https://github.com/akkadotnet/akka.net/pull/8952) - Akka.Reminders now ships on the 1.5 line, dual-targeted at `netstandard2.0` and `net10.0` so it reaches .NET Framework 4.8 through .NET 10. This is a port rather than a backport: the module is new to 1.5, so the whole thing was re-targeted onto the branch. It ships five packages — `Akka.Reminders`, `Akka.Reminders.Sql`, `Akka.Reminders.SqlServer`, `Akka.Reminders.PostgreSql` and `Akka.Reminders.Sqlite` — renamed from `Aaron.Akka.Reminders*` and now sharing the Akka.NET version number. A golden-database spec proves the new packages read data written by the released `Aaron.Akka.Reminders` 1.5.73 packages. AOT is not supported on Akka.NET 1.5, so the module carries no AOT annotations here. The module ships no `reference.conf` and no MultiNode specs; serializer registration goes through the Akka.Hosting API, so HOCON-only users have no configuration surface for it.
* [End every older live occurrence when a newer one is sent](https://github.com/akkadotnet/akka.net/pull/8971) - A recurring reminder could deliver an older occurrence after a newer one when its interval was well below `MaxSlippage` and its shard region was missing for a while and then came back. The recipient got the newer occurrence and then the older one, and both acknowledgements succeeded. When the newest occurrence of a series moves to `AwaitingAck`, every older live occurrence of that series now expires in the same storage commit. Fixes [#8965](https://github.com/akkadotnet/akka.net/issues/8965).
* [Cap the older occurrences one send ends at 256](https://github.com/akkadotnet/akka.net/pull/8975) - The fix above expires `ceil(earliness / interval)` older occurrences per early send with no upper bound, and Reminders accepts any interval above zero. A 1 ms interval put about 5,000 expiries in one commit, and a sub-millisecond interval could put millions into the scheduler's memory. The cap is 256 per send, nearest first. No interval of about 20 ms or more at the default 5 s `MaxSlippage` can reach it. Below that, during a shard region outage, an older occurrence more than 256 intervals back can still be sent after a newer one; `failure-modes.md` documents the limit.

**Akka.Persistence**
* [Do not run the `PersistAll` completion callback when the journal rejects the batch](https://github.com/akkadotnet/akka.net/pull/8950) - The completion callback of a `PersistAll` or `PersistAllAsync` call ran even when the journal rejected the batch, so an actor could act on a write that never happened. The defect was present since 1.5.57. Fixes [#8948](https://github.com/akkadotnet/akka.net/issues/8948).
* [Run stashed commands in order when an async persist handler completes asynchronously](https://github.com/akkadotnet/akka.net/pull/8943) - A persistent actor ran stashed commands out of order when an async `Persist` handler, or the async completion of `PersistAll`, did not complete synchronously: two calls unstashed in the same turn. These overloads first shipped in 1.5.57. Fixes [#8942](https://github.com/akkadotnet/akka.net/issues/8942).

**Docs**
* [TLS certificate rotation article](https://github.com/akkadotnet/akka.net/pull/8961) - New article covering how a node picks its certificate and when a renewed one is used, how to rotate, changing an existing setup, trust by CA and name, loading from Azure Key Vault, rotating with a rolling restart, and troubleshooting. It leads with Akka.Hosting, then HOCON, then code. `security.md` now says which certificate options can rotate without a restart, and no longer claims that revocation is checked, which the DotNetty transport does not do. A follow-up ([#8970](https://github.com/akkadotnet/akka.net/pull/8970)) corrected the article's note about `CustomValidator`, which does apply to thumbprint and single-file certificates since [#8963](https://github.com/akkadotnet/akka.net/pull/8963).

**Build and tests**
* [Skip the simultaneous-disassociate graceful-close spec on .NET Framework](https://github.com/akkadotnet/akka.net/pull/8900) - On net48 the tests load Akka.Remote's `netstandard2.0` build, where `HalfClose` falls back to a full close. When both sides disassociate at once, one side can close while the other's frames are still unread and its kernel sends an RST, so the spec failed intermittently. The two sibling "no reset" tests in the class already skip on .NET Framework for the same reason. This changes no product code.
* Akka.Reminders CI lane - The new module adds a Linux-only `net_tests_reminders_linux` lane with its own Incrementalist config, because `Akka.Reminders.Migration.Tests` starts SQL Server and PostgreSQL containers unconditionally and the Windows agents have no Docker. `src/contrib/reminders/**` is excluded from the Windows test configs.

1 contributor since release 1.5.74

| COMMITS | LOC+ | LOC- | AUTHOR |
| --- | --- | --- | --- |
| 13 | 40157 | 552 | Aaron Stannard |

To see the full set of changes in Akka.NET v1.5.75, [click here](https://github.com/akkadotnet/akka.net/milestone/158?closed=1).