API Improvement: Store options reference in AkkaPersistenceJournalBuilder and AkkaPersistenceSnapshotBuilder

[Aaronontheweb]

Description

Currently, when implementing connectivity health checks for persistence plugins, extension methods like WithConnectivityCheck() require the options object to be passed explicitly, even though those options were already provided when configuring the journal or snapshot store.

Current Pattern (Redundant)

var journalOptions = new AzureTableStorageJournalOptions(isDefault: true)
{
    ConnectionString = connectionString,
    TableName = "akkajournal"
};

builder.WithAzureTableJournal(journalOptions, journal =>
{
    journal.WithConnectivityCheck(journalOptions);  // ❌ Options passed again
});

Desired Pattern

var journalOptions = new AzureTableStorageJournalOptions(isDefault: true)
{
    ConnectionString = connectionString,
    TableName = "akkajournal"
};

builder.WithAzureTableJournal(journalOptions, journal =>
{
    journal.WithConnectivityCheck();  // ✅ Builder already has options
});

Root Cause

The AkkaPersistenceJournalBuilder and AkkaPersistenceSnapshotBuilder classes don't store a reference to the options object that was passed to WithJournal() or WithSnapshot(). They only store:

• JournalId / SnapshotStoreId (string)
• Builder (AkkaConfigurationBuilder)
• Event adapters
• Health check registrations

Proposed Solution

Add an Options property to both builders:

public sealed class AkkaPersistenceJournalBuilder
{
    // Existing properties
    internal readonly string JournalId;
    internal readonly AkkaConfigurationBuilder Builder;
    
    // NEW: Store the options object
    internal readonly JournalOptions? Options;

    public AkkaPersistenceJournalBuilder(string journalId, AkkaConfigurationBuilder builder, JournalOptions? options = null)
    {
        JournalId = journalId;
        Builder = builder;
        Options = options;
    }
}

This would allow extension methods to access the options without requiring them to be passed explicitly:

public static AkkaPersistenceJournalBuilder WithConnectivityCheck(
    this AkkaPersistenceJournalBuilder builder,
    HealthStatus unHealthyStatus = HealthStatus.Unhealthy,
    string? name = null,
    string[]? tags = null)
{
    if (builder.Options is not AzureTableStorageJournalOptions azureOptions)
        throw new InvalidOperationException("WithConnectivityCheck requires AzureTableStorageJournalOptions");
    
    // Use azureOptions.ConnectionString, azureOptions.Identifier, etc.
    // ...
}

Impact

This affects all persistence plugins implementing connectivity health checks:

• ✅ Akka.Persistence.Sql
• ✅ Akka.Persistence.Redis
• ✅ Akka.Persistence.MongoDB
• ✅ Akka.Persistence.Azure (in progress)

All currently use the redundant pattern of requiring options to be passed explicitly.

Backwards Compatibility

This would be a non-breaking change since:

1. The Options property could be added as optional/nullable
2. Existing extension methods would continue to work
3. New extension methods could check for Options != null before using it

Related

• Original connectivity health checks epic: Epic: Add Connectivity Health Checks for Akka.Persistence Plugins #678