Skip to content

Commit 4c18c5e

Browse files
committed
feat(WP-1.9): CommandRejected replies and lease fair-share
- CommandRejected<TCommand> (MessageKind.Reply): a process manager that reacts to it gets the owner's rejection through its correlation. The sender adds an sf-reply-to header for locally owned commands and ReplyOnReject() routes when it registered the reply type; the owner enqueues the reply in the same commit as the rejection, built from the received command JSON. The header never propagates to caused messages. The generator registers CommandRejected<T> as "{command}.rejected" and SF0010 requires it in the module's JSON context. - Bank: MoneyTransfer fails at once on CommandRejected<Withdraw>; E2E-14 now times out on a rejected deposit and compensates; E2E-15 added. - INodeRegistry (optional storage port; in-memory and PostgreSQL): heartbeats on the store clock, live count by role. The subscription engine takes at most ceil(leases / live nodes), releases one excess lease per pass and hands every lease back on graceful stop. - Unit tests UT-SUB-01/05/06/08/09/10/12/17, UT-PRJ-01, UT-PM-01/10..13; PostgreSQL node registry test.
1 parent f43c80d commit 4c18c5e

28 files changed

Lines changed: 794 additions & 18 deletions

File tree

‎docs/v3.0.0/implementation/STATUS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Updated in the PR that completes a work package (CONTRIBUTING.md). Status values
1717
| WP-1.6 | Command processing + temporal reads | 3 | done | CommandProcessor, CommandSender, AggregateReader (AsOf), snapshots (interval, schema hash); the aggregate cache landed with WP-2.5 |
1818
| WP-1.7 | Middleware and diagnostics | 1.5 | done | MessagePipeline, built-in middleware, ErrorClassifier, SourceFlowMetrics with InstrumentAdvice; UT-MW |
1919
| WP-1.8 | Outbox, scheduler, transport SPI, in-memory broker, receive pipeline | 3.5 | done | Transport SPI, InMemoryBroker, OutboxRelay, ReceiveEndpoint, dead letters; TCK-01..12 green on the in-memory broker |
20-
| WP-1.9 | Subscriptions, projections, process managers, event handlers | 4 | in progress | SubscriptionEngine (fenced, partitioned), projections, process managers, event handlers done; CommandRejected replies (E2E-15) and node fair-share pending |
20+
| WP-1.9 | Subscriptions, projections, process managers, event handlers | 4 | done | SubscriptionEngine (fenced, partitioned, adaptive batches, park policy with per-event isolation), projections, process managers (incl. `CommandRejected<T>` replies: `sf-reply-to` header for local owners and `ReplyOnReject()` routes, reply committed with the rejection, ADR-018), event handlers; `INodeRegistry` heartbeat + fair-share rebalancer (one lease released per pass, graceful hand-back on stop). UT-SUB-01/05/06/08/09/10/12/17, UT-PRJ-01, UT-PM-01/10..13, E2E-09..15. Repartition and blue/green rebuild (UT-SUB-21..28) and the `projection skip` Stop policy come with the CLI (WP-4.1) |
2121
| WP-1.10 | Hosting, roles, tenancy context | 1.5 | done | AddSourceFlow, SourceFlowBuilder Use* slots, roles, SourceFlowHost lifecycle, health check |
2222
| WP-1.11 | `SourceFlow.Testing` | 2.5 | done | SourceFlowTestHost, AggregateSpec, ProcessManagerSpec, ProjectionSpec, approvals; UT-TST |
2323
| WP-1.12 | Schema catalog | 2 | todo | |

‎samples/Bank/Bank.Transfers/Transfers.cs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,15 @@ public Reaction React(MoneyDeposited e, ReactionContext<TransferId> ctx)
169169
: Reaction.Ignore;
170170
}
171171

172+
/// <summary>The source account rejected the withdrawal (for example insufficient funds): fail now (ADR-018).</summary>
173+
public Reaction React(CommandRejected<Withdraw> r, ReactionContext<TransferId> ctx)
174+
{
175+
ArgumentNullException.ThrowIfNull(r);
176+
return Stage == TransferStage.Withdrawing
177+
? Reaction.Send(new FailTransfer(ctx.Id, r.Error.Code)).AndComplete()
178+
: Reaction.Ignore;
179+
}
180+
172181
/// <summary>The timeout fired: fail, compensating a withdrawal that already happened.</summary>
173182
public Reaction React(TransferTimedOut e, ReactionContext<TransferId> ctx)
174183
{
@@ -194,6 +203,7 @@ public sealed partial class TransfersModule;
194203
[JsonSerializable(typeof(TransferFailed))]
195204
[JsonSerializable(typeof(TransferTimedOut))]
196205
[JsonSerializable(typeof(MoneyTransfer))]
206+
[JsonSerializable(typeof(CommandRejected<Withdraw>))]
197207
[JsonSerializable(typeof(Transfer))]
198208
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
199209
public sealed partial class TransfersJsonContext : JsonSerializerContext;

‎src/Core/SourceFlow.Generators/CompilationInventory.cs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ internal sealed class CompilationInventory
1515
private readonly ConcurrentBag<INamedTypeSymbol> _messages = new();
1616
private readonly ConcurrentBag<INamedTypeSymbol> _modules = new();
1717
private readonly ConcurrentBag<INamedTypeSymbol> _stateTypes = new();
18+
private readonly ConcurrentBag<(INamedTypeSymbol Reply, INamedTypeSymbol Process)> _replies = new();
1819
private readonly ConcurrentBag<(ITypeSymbol Command, ITypeSymbol Aggregate)> _handled = new();
1920
private readonly ConcurrentBag<(INamedTypeSymbol Command, ITypeSymbol Aggregate)> _commands = new();
2021

@@ -42,6 +43,13 @@ public void Collect(INamedTypeSymbol type)
4243
if (type.FindAttribute(KnownNames.ProcessManagerAttribute) is not null)
4344
{
4445
_stateTypes.Add(type);
46+
foreach (IMethodSymbol react in type.GetMembers("React").OfType<IMethodSymbol>())
47+
{
48+
if (react.Parameters.Length == 2 && react.Parameters[0].Type is INamedTypeSymbol { IsGenericType: true } reply && reply.Is(KnownNames.CommandRejected))
49+
{
50+
_replies.Add((reply, type));
51+
}
52+
}
4553
}
4654

4755
if (type.FindAttribute(KnownNames.AggregateAttribute) is { } aggregate)
@@ -118,6 +126,18 @@ private void ReportJsonContexts(CompilationAnalysisContext context)
118126
}
119127
}
120128

129+
foreach ((INamedTypeSymbol reply, INamedTypeSymbol process) in _replies)
130+
{
131+
if (!listed.Contains(reply))
132+
{
133+
var properties = ImmutableDictionary<string, string?>.Empty
134+
.Add(JsonContextCodeFix.ContextKey, SymbolExtensions.MetadataName(jsonContext))
135+
.Add(JsonContextCodeFix.TypeKey, reply.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat));
136+
context.ReportDiagnostic(Diagnostic.Create(Diagnostics.MissingJsonType, process.Locations.FirstOrDefault(l => l.IsInSource) ?? Location.None, properties,
137+
reply.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat), jsonContext.Name));
138+
}
139+
}
140+
121141
foreach (INamedTypeSymbol required in _messages.Concat(_stateTypes).Distinct<INamedTypeSymbol>(SymbolEqualityComparer.Default))
122142
{
123143
if (!listed.Contains(required) && required.Locations.Any(l => l.IsInSource))

‎src/Core/SourceFlow.Generators/Emitters.cs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,11 @@ public static string Module(
326326
w.Line($"builder.AddMessage<{m.FullName}>({Literal.Of(m.LogicalName)}, {m.Version.ToString(CultureInfo.InvariantCulture)});");
327327
}
328328

329+
foreach (RejectionModel r in processes.SelectMany(p => p.Rejections).Distinct().OrderBy(r => r.LogicalName, System.StringComparer.Ordinal))
330+
{
331+
w.Line($"builder.AddMessage<{r.FullName}>({Literal.Of(r.LogicalName)}, {r.Version.ToString(CultureInfo.InvariantCulture)});");
332+
}
333+
329334
foreach (HandlerModel h in handlers.Where(h => h.Kind == HandlerKind.Upcaster).OrderBy(h => h.FullName, System.StringComparer.Ordinal))
330335
{
331336
w.Line($"builder.AddUpcaster<{h.First}, {h.Second}, {h.FullName}>();");

‎src/Core/SourceFlow.Generators/Infrastructure.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ internal static class KnownNames
121121
public const string Reaction = "SourceFlow.Reaction";
122122
public const string ReactionContext = "SourceFlow.ReactionContext`1";
123123
public const string EventContext = "SourceFlow.EventContext";
124+
public const string CommandRejected = "SourceFlow.CommandRejected`1";
124125
}
125126

126127
internal static class SymbolExtensions

‎src/Core/SourceFlow.Generators/ModelBuilder.cs‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ private static IEnumerable<MemberModel> Members(INamedTypeSymbol type)
174174
var reacted = new List<string>();
175175
var correlated = new List<string>();
176176
var textCorrelated = new List<string>();
177+
var rejections = new List<RejectionModel>();
177178
foreach (IMethodSymbol method in type.GetMembers().OfType<IMethodSymbol>())
178179
{
179180
if (!method.IsStatic && method.Name == "React" && method.Parameters.Length == 2
@@ -183,6 +184,14 @@ private static IEnumerable<MemberModel> Members(INamedTypeSymbol type)
183184
&& !method.Parameters[0].Type.Is(KnownNames.Message))
184185
{
185186
reacted.Add(method.Parameters[0].Type.FullName());
187+
if (method.Parameters[0].Type is INamedTypeSymbol { IsGenericType: true } reply
188+
&& reply.Is(KnownNames.CommandRejected)
189+
&& reply.TypeArguments[0].FindAttribute(KnownNames.MessageTypeAttribute) is { ConstructorArguments.Length: > 0 } commandType
190+
&& commandType.ConstructorArguments[0].Value is string commandName)
191+
{
192+
int commandVersion = commandType.ConstructorArguments.Length > 1 && commandType.ConstructorArguments[1].Value is int v ? v : 1;
193+
rejections.Add(new RejectionModel(reply.FullName(), commandName + ".rejected", commandVersion));
194+
}
186195
}
187196
else if (method.IsStatic && method.Name == "CorrelateBy" && method.Parameters.Length == 1
188197
&& SymbolEqualityComparer.Default.Equals(method.ReturnType, idType))
@@ -205,7 +214,8 @@ private static IEnumerable<MemberModel> Members(INamedTypeSymbol type)
205214
idType.FullName(),
206215
reacted.Distinct().OrderBy(x => x, System.StringComparer.Ordinal).ToEquatableArray(),
207216
correlated.Distinct().OrderBy(x => x, System.StringComparer.Ordinal).ToEquatableArray(),
208-
textCorrelated.Distinct().OrderBy(x => x, System.StringComparer.Ordinal).ToEquatableArray());
217+
textCorrelated.Distinct().OrderBy(x => x, System.StringComparer.Ordinal).ToEquatableArray(),
218+
rejections.Distinct().OrderBy(x => x.LogicalName, System.StringComparer.Ordinal).ToEquatableArray());
209219
}
210220

211221
public static SessionProjectionModel? SessionProjection(GeneratorAttributeSyntaxContext context, CancellationToken cancellationToken)

‎src/Core/SourceFlow.Generators/Models.cs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,11 @@ internal sealed record ProcessManagerModel(
4343
string IdType,
4444
EquatableArray<string> ReactedMessages,
4545
EquatableArray<string> CorrelatedMessages,
46-
EquatableArray<string> TextCorrelatedMessages);
46+
EquatableArray<string> TextCorrelatedMessages,
47+
EquatableArray<RejectionModel> Rejections);
48+
49+
/// <summary>A <c>CommandRejected&lt;T&gt;</c> a process manager reacts to: registered as <c>{T's name}.rejected</c>.</summary>
50+
internal sealed record RejectionModel(string FullName, string LogicalName, int Version);
4751

4852
internal enum KeySource
4953
{

‎src/Core/SourceFlow.Net/Diagnostics/Log.cs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ internal static partial class Log
2929
[LoggerMessage(1105, LogLevel.Information, "Retention cleanup deleted {Inbox} inbox rows and {DeadLetters} resolved dead letters")]
3030
public static partial void RetentionPurged(ILogger logger, int inbox, int deadLetters);
3131

32+
[LoggerMessage(1106, LogLevel.Warning, "Node heartbeat failed; the lease fair share uses the last known node count")]
33+
public static partial void HeartbeatFailed(ILogger logger, Exception exception);
34+
3235
[LoggerMessage(1201, LogLevel.Warning, "Message {MessageId} ({MessageType}) failed transiently on attempt {Attempt}; redelivering after {Delay}")]
3336
public static partial void ReceiveRetry(ILogger logger, Exception exception, string messageId, string messageType, int attempt, TimeSpan delay);
3437

‎src/Core/SourceFlow.Net/Domain/Decisions.cs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ namespace SourceFlow;
44
/// <param name="Code">A stable, dot-separated code, for example <c>account.insufficient_funds</c>.</param>
55
/// <param name="Message">A human-readable description.</param>
66
/// <param name="Details">Optional structured details.</param>
7-
public sealed record Error(string Code, string Message, IReadOnlyDictionary<string, object?>? Details = null)
7+
public sealed record Error(
8+
[property: System.Text.Json.Serialization.JsonPropertyName("code")] string Code,
9+
[property: System.Text.Json.Serialization.JsonPropertyName("message")] string Message,
10+
[property: System.Text.Json.Serialization.JsonPropertyName("details")] IReadOnlyDictionary<string, object?>? Details = null)
811
{
912
/// <summary>The command is structurally invalid, for example its target id is the default value (GAP-20).</summary>
1013
public static Error InvalidCommand(string message)

‎src/Core/SourceFlow.Net/Domain/Messages.cs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,44 @@ public enum MessageKind
3434

3535
/// <summary>A timeout (<see cref="ITimeout"/>).</summary>
3636
Timeout = 4,
37+
38+
/// <summary>A reply to a sender, such as <see cref="CommandRejected{TCommand}"/>.</summary>
39+
Reply = 5,
40+
}
41+
42+
/// <summary>A command owner's reply that a command was rejected (ADR-018, doc 03 §6.1).</summary>
43+
public interface ICommandRejected : IMessage
44+
{
45+
/// <summary>Why the command was rejected.</summary>
46+
Error Error { get; }
47+
}
48+
49+
/// <summary>
50+
/// The reply a process manager receives when a command it sent was rejected by its owner (ADR-018). It reaches the
51+
/// sending instance through the correlation when the command is owned locally or routed with <c>ReplyOnReject()</c>.
52+
/// React to it with <c>React(CommandRejected&lt;TCommand&gt; r, ReactionContext&lt;TId&gt; ctx)</c> and list it in the
53+
/// module's JSON context. Its message type is <c>{command type}.rejected</c> with the command's version.
54+
/// </summary>
55+
/// <typeparam name="TCommand">The rejected command.</typeparam>
56+
/// <param name="Command">The command as sent.</param>
57+
/// <param name="Error">Why it was rejected.</param>
58+
public sealed record CommandRejected<TCommand>(
59+
[property: System.Text.Json.Serialization.JsonPropertyName("command")] TCommand Command,
60+
[property: System.Text.Json.Serialization.JsonPropertyName("error")] Error Error) : ICommandRejected
61+
where TCommand : class, ICommand;
62+
63+
/// <summary>Conventions of command replies.</summary>
64+
public static class CommandReplies
65+
{
66+
/// <summary>The reserved header carrying the endpoint a rejection reply goes to. It never propagates to caused messages.</summary>
67+
public const string ReplyToHeader = "sf-reply-to";
68+
69+
/// <summary>The message type name of the rejection reply for a command type.</summary>
70+
public static string RejectedTypeName(string commandTypeName)
71+
{
72+
ArgumentException.ThrowIfNullOrWhiteSpace(commandTypeName);
73+
return commandTypeName + ".rejected";
74+
}
3775
}
3876

3977
/// <summary>Thrown when generated dispatch receives a message type it was not built for.</summary>

0 commit comments

Comments
 (0)