Process Manager via Handlers sample#2579
Merged
jeremydmiller merged 8 commits intoJasperFx:mainfrom Apr 26, 2026
Merged
Conversation
…tion via existing Wolverine + Marten features Implement worked sample showing process manager pattern using `FetchForWriting`, `[AggregateHandler]`, `MartenOps.StartStream`, and inline snapshots—no new base class required. Includes order fulfillment flow with state type, events, commands, start handler, integration test, and DISCOVERIES.md capturing corrected expectations (start handler must return `IStartStream`, not use `[AggregateHandler]` due to OnMissing defaults). Adds process-manager-via-handlers.md guide skeleton pending implementation phases. - Add ProcessManagerSample project with OrderFulfillmentState, events, commands, handlers - Add StartOrderFulfillmentHandler returning IStartStream via MartenOps.StartStream - Add ProcessManagerSample.Tests with IntegrationContext, AppFixture, when_starting_a_fulfillment - Add DISCOVERIES.md documenting confirmed/corrected expectations and gotchas - Add process-manager-via-handlers.md guide structure with building-blocks section - Add OrderFulfillment/README.md outlining sample architecture - Wire inline snapshot projection and Wolverine integration in Program.cs - Add appsettings.json with Marten connection string
…tests for ProcessManagerSample Implement PaymentConfirmedHandler, ItemsReservedHandler, ShipmentConfirmedHandler, and CancelOrderFulfillmentHandler as aggregate handlers returning `Events` with terminal-state and idempotency guards. Add OrderFulfillmentState `Apply` methods for all events. Expand events with integration types (PaymentConfirmed, ItemsReserved, ShipmentConfirmed) and terminal events (OrderFulfillmentCompleted, OrderFulfillmentCancelled). Add CancelOrderFulfillment compensating command. Include HandlerUnitTests covering pure-function handler logic and integration tests verifying happy-path completion, out-of-order arrival, duplicate handling, and cancellation behavior. - Add PaymentConfirmedHandler/ItemsReservedHandler/ShipmentConfirmedHandler with completion guards - Add CancelOrderFulfillmentHandler appending OrderFulfillmentCancelled - Add OrderFulfillmentState.Apply methods for all event types - Add PaymentConfirmed, ItemsReserved, ShipmentConfirmed, OrderFulfillmentCompleted, OrderFulfillmentCancelled events - Add CancelOrderFulfillment command with Reason property - Add HandlerUnitTests verifying guard logic, completion detection, and idempotency - Add when_completing_a_fulfillment tests for happy path, out-of-order, duplicates - Add when_cancelling_a_fulfillment tests for mid-process cancel and post-cancel no-ops - Expand process-manager-via-handlers.md with complete Step 3–8 recipe and testing guidance
…ncing via state guards Implement `PaymentTimeoutHandler` as pure aggregate handler using terminal-state and payment-confirmed guards to make timeout a silent no-op when process completes or payment arrives before scheduler fires. Extend `StartOrderFulfillmentHandler` to schedule `PaymentTimeout` via `(IStartStream, OutgoingMessages)` tuple return with configurable delay. Add comprehensive timeout tests covering unit-level guard behavior, scheduler-fired cancellation, and early-payment silencing with polling helper for scheduler observation. - Add PaymentTimeoutHandler returning Events with IsTerminal/PaymentConfirmed guards - Add PaymentTimeout command with OrderFulfillmentStateId correlation - Extend StartOrderFulfillmentHandler tuple return scheduling PaymentTimeout via OutgoingMessages.Delay - Add PaymentTimeoutWindow optional parameter to StartOrderFulfillment for test override - Add DefaultPaymentTimeoutWindow constant (15 minutes) to StartOrderFulfillmentHandler - Add when_payment_times_out tests: unit guards, scheduler cancellation, payment-before-timeout silencing - Add WaitForCondition polling helper for scheduler integration test observation - Update DISCOVERIES.md documenting tuple-return composition, scheduler timing, and "let state decide" idiom - Update recipe adjustments removing "to be validated" banner and recommending state-guard pattern
…on, testing patterns, friction points, and Saga comparison Finalize Phase 5–6 sections removing "to be validated" banner and adding timeout handler, scheduler integration tests, comprehensive friction-point analysis, and Saga decision criteria. Clarify tuple-return composition for `(IStartStream, OutgoingMessages)`, document "let state decide" pattern avoiding explicit timeout cancellation, and provide `WaitForCondition` polling helper for scheduler-fired integration tests. Expand friction points with honest accounting of distributed completion logic, guard-line overhead, and silent failure modes. Add when-to-use-Saga guidance covering discoverability, framework-managed lifecycle, and team fluency trade-offs. - Remove "to be validated" banner from Step 6 section - Clarify tuple-return unpacker behavior composing IMartenOp with OutgoingMessages - Add PaymentTimeoutHandler example with terminal-state and payment-confirmed guards - Document "let state decide" idiom vs explicit-cancel approach for timeouts - Add WaitForCondition polling helper for scheduler integration test observation - Expand testing section with scheduler-fired message patterns and timing guidance - Add complete "The Friction Points
…o process-manager-via-handlers guide Replace placeholder with comprehensive reference implementation from ProcessManagerSample including OrderFulfillmentState projection, all event/command types, handler implementations (start, continue steps, cancel, timeout), Marten+Wolverine wiring, unit tests demonstrating pure-function handler testing, and integration tests covering happy-path end-to-end flow. Add DCB enhancement section documenting `[BoundaryModel]` usage for cross-stream invariants with EventTagQuery patterns and sharp edges. Update navigation to include new guide in Marten durability sidebar. - Add complete OrderFulfillmentState.cs with Apply methods and terminal-state guards - Add Events.cs and Commands.cs with all domain types - Add all handler implementations: Start, PaymentConfirmed, ItemsReserved, ShipmentConfirmed, Cancel, PaymentTimeout - Add Program.cs showing Marten snapshot projection and Wolverine integration wiring - Add unit test example for pure-function payment-confirmed completion logic - Add integration test example verifying happy-path event stream and projected state - Add DCB enhancement section with BoundaryModel usage, EventTagQuery patterns, and concurrency gotchas - Add guide to .vitepress/config.mts Marten durability navigation section
…lag ConcurrencyException scoping gap Expand process-manager-via-handlers guide to document `ExistingStreamIdCollisionException` behavior when duplicate start commands arrive: explain exception type, propagation through `InvokeMessageAndWaitAsync`, transaction rollback, and idempotent handling strategies. Add `starting_the_same_process_twice_throws_and_first_start_wins` test verifying exception properties and first-start-wins semantics. Flag in Friction Points that `ExistingStreamIdCollisionException` inherits from `MartenException` not `ConcurrencyException`, requiring broader retry policy scoping to catch duplicate-start failures. - Add duplicate-start exception documentation in Step 4a corollary paragraph - Add starting_the_same_process_twice_throws_and_first_start_wins test with rollback verification - Add friction point note flagging ExistingStreamIdCollisionException inheritance gotcha - Close DISCOVERIES.md question 3 documenting exception behavior and test reference
… of singular TargetFramework
… discoveries Refine the "Process Manager via Handlers" guide and associated sample project files to reflect the final implementation state. This includes clarifying the asymmetry between start and continue handlers, updating test counts, and documenting final architectural decisions. - Clarify start vs. continue handler asymmetry in guide and sample README - Update test counts and implementation notes to match the full sample suite - Finalize DISCOVERIES.md with a historical record of applied recipe adjustments - Document decision to keep concurrency race behavior as docs-only to avoid flaky integration tests - Add focus notes to simplified code snippets in documentation for better clarity
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a worked sample and documentation for building an event-sourced Process Manager using existing Wolverine + Marten features. Complements Sagas for teams that want event-sourced process state, a replayable audit log, and pure-function handler tests. No new framework types, no new packages.
Changes
src/Samples/ProcessManagerSample/): state type, events, commands, and six handlers (start + three continue + cancel + payment timeout). Registered inwolverine.slnxunder/Samples/ProcessManagerSample/.docs/guide/durability/marten/process-manager-via-handlers.mdwith seven sections: Introduction, Building Blocks, Recipe, Worked Example, Friction Points, When to Use Saga Instead, and DCB Enhancement. Added to the Marten Integration nav group indocs/.vitepress/config.mts, immediately after Sagas.DISCOVERIES.md: internal findings log in the sample directory, scoped for the futureProcessManager<TState>framework proposal.Validation
dotnet buildon the sample: cleandotnet teston the sample: 20 / 20 greenvitepress build docs: clean render, no broken nav linksdotnet run→ HTTP POST → event persisted → scheduler fires timeout → cancellation event appended → inline snapshot projection correctNotes
ProcessManager<TState>framework-type proposal;DISCOVERIES.mdis the bridge between the two.wait-for-scheduled-messagetest helper.