Skip to content
Closed
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The [AWS SDK for .NET credential and profile resolution chain](https://docs.aws.

<xref:Orleans.Configuration.DynamoDBStorageOptions.ServiceId> must remain stable across deployments that share the same logical application state. The provider uses optimistic concurrency and rejects stale writes.

When <xref:Orleans.Configuration.DynamoDBStorageOptions.ServiceId> is empty, the keys start with an underscore instead of <xref:Orleans.Configuration.ClusterOptions.ServiceId>, unlike the other grain storage providers, and the provider logs a warning. Set <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId> to use <xref:Orleans.Configuration.ClusterOptions.ServiceId> instead. State written before then stays under its old key unless <xref:Orleans.Configuration.DynamoDBStorageOptions.MigrateLegacyKeys> is also set: a grain with no state under the new key then reads it from the old one, and its next write moves it, in one transaction. Enable the migration once every silo runs a version that supports it, with the same options on every silo: a silo still writing the old keys, from an older version or with <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId> set to `false`, is not protected from a migrating silo moving or deleting state it recreates, since an item recreated after <xref:Orleans.Configuration.DynamoDBStorageOptions.DeleteStateOnClear> starts again at ETag 0. Set <xref:Orleans.Configuration.DynamoDBStorageOptions.MigrateLegacyKeys> to `false` when every grain has been written, to spare the second read for grains that have no state. The provider records its choice in the table and keeps it while these options are left unset.

## Serialization

Set <xref:Orleans.Configuration.DynamoDBStorageOptions.GrainStorageSerializer> to customize the stored representation. Changing serializers doesn't rewrite existing items, so the replacement must read the previous representation or be accompanied by a migration.
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,16 @@ public void Configure(ISiloBuilder builder, string? name, IConfigurationSection
options.ServiceId = serviceId;
}

if (bool.TryParse(configurationSection[nameof(options.UseClusterServiceId)], out var useClusterServiceId))
{
options.UseClusterServiceId = useClusterServiceId;
}

if (bool.TryParse(configurationSection[nameof(options.MigrateLegacyKeys)], out var migrateLegacyKeys))
{
options.MigrateLegacyKeys = migrateLegacyKeys;
Comment thread
Laurianti marked this conversation as resolved.
Resolved
}

var tableName = configurationSection[nameof(options.TableName)];
if (!string.IsNullOrEmpty(tableName))
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ public static IServiceCollection AddDynamoDBGrainStorage(this IServiceCollection
services.AddTransient<IConfigurationValidator>(sp => new DynamoDBGrainStorageOptionsValidator(sp.GetRequiredService<IOptionsMonitor<DynamoDBStorageOptions>>().Get(name), name));
services.ConfigureNamedOptionForLogging<DynamoDBStorageOptions>(name);
services.AddTransient<IPostConfigureOptions<DynamoDBStorageOptions>, DefaultStorageProviderSerializerOptionsConfigurator<DynamoDBStorageOptions>>();
services.TryAddEnumerable(ServiceDescriptor.Transient<IPostConfigureOptions<DynamoDBStorageOptions>, DynamoDBStorageClusterServiceIdConfigurator>());
return services.AddGrainStorage(name, DynamoDBGrainStorageFactory.Create);
}
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Orleans.Persistence.DynamoDB;
using Orleans.Runtime;
using Orleans.Storage;
Expand All @@ -12,9 +14,33 @@ public class DynamoDBStorageOptions : DynamoDBClientOptions, IStorageProviderSer
{
/// <summary>
/// Gets or sets a unique identifier for this service, which should survive deployment and redeployment.
/// When left empty, see <see cref="UseClusterServiceId"/>.
/// </summary>
public string ServiceId { get; set; } = string.Empty;

/// <summary>
/// Gets or sets whether an empty <see cref="ServiceId"/> falls back to <see cref="ClusterOptions.ServiceId"/>,
/// as the other grain storage providers do. When <see langword="false"/>, an empty <see cref="ServiceId"/> is used
/// as it is, and every key starts with an underscore. When not set, the key format already recorded in the table is
/// kept, and a new table uses the empty <see cref="ServiceId"/>; this default changes in a future major version.
/// Has no effect when <see cref="ServiceId"/> is set.
/// </summary>
public bool? UseClusterServiceId { get; set; }

/// <summary>
/// Gets or sets whether state written with an empty <see cref="ServiceId"/> is read when a grain has no state under
/// <see cref="ClusterOptions.ServiceId"/>, and moved there on the grain's next write. When not set, a migration
/// recorded in the table goes on. Has an effect only when <see cref="ClusterOptions.ServiceId"/> is used for an
/// empty <see cref="ServiceId"/>. Every silo must run with the same options while it is set: a silo still writing
/// the keys with an empty <see cref="ServiceId"/> is not protected from a migrating one.
/// </summary>
public bool? MigrateLegacyKeys { get; set; }

/// <summary>
/// The <see cref="ClusterOptions.ServiceId"/> of the silo, used when <see cref="UseClusterServiceId"/> applies.
/// </summary>
internal string ClusterServiceId { get; set; } = ClusterOptions.DefaultServiceId;

/// <summary>
/// Use Provisioned Throughput for tables
/// </summary>
Expand Down Expand Up @@ -71,6 +97,24 @@ public class DynamoDBStorageOptions : DynamoDBClientOptions, IStorageProviderSer
public IGrainStorageSerializer GrainStorageSerializer { get; set; } = null!;
}

/// <summary>
/// Supplies <see cref="DynamoDBStorageOptions"/> with the <see cref="ClusterOptions.ServiceId"/> of the silo.
/// </summary>
internal sealed class DynamoDBStorageClusterServiceIdConfigurator(IServiceProvider serviceProvider) : IPostConfigureOptions<DynamoDBStorageOptions>
{
public void PostConfigure(string? name, DynamoDBStorageOptions options)
{
// a provider-specific override first, as GetProviderClusterOptions does, without requiring ClusterOptions
var clusterOptions = (name is null ? null : serviceProvider.GetKeyedService<ClusterOptions>(name))
?? serviceProvider.GetService<IOptions<ClusterOptions>>()?.Value;

if (clusterOptions?.ServiceId is { Length: > 0 } serviceId)
{
options.ClusterServiceId = serviceId;
}
}
}

/// <summary>
/// Configuration validator for DynamoDBStorageOptions
/// </summary>
Expand Down
Loading