| | | 1 | | namespace AsyncResponse; |
| | | 2 | | |
| | | 3 | | /// <summary> |
| | | 4 | | /// Marker for payload models awaited through <see cref="IAsyncResponseBuilder.For{T}(string)"/> and |
| | | 5 | | /// <see cref="IAsyncResponseBuilder.For{T}()"/>. Implement this on your DTO/class/record to opt in. |
| | | 6 | | /// Using an interface intentionally excludes primitive and scalar BCL types such as |
| | | 7 | | /// <see cref="string"/>, <see cref="int"/>, <see cref="bool"/>, <see cref="Guid"/>, and |
| | | 8 | | /// <see cref="DateTime"/>. |
| | | 9 | | /// </summary> |
| | | 10 | | public interface IAsyncResponsePayload |
| | | 11 | | { |
| | | 12 | | /// <summary> |
| | | 13 | | /// Decides — for the <em>lost-subscriber</em> recovery path only — what a late response of this |
| | | 14 | | /// type should do to the flow: <see cref="RecoveryAction.Resume"/> it, |
| | | 15 | | /// <see cref="RecoveryAction.Fail"/> it, or <see cref="RecoveryAction.KeepWaiting"/> because |
| | | 16 | | /// this message is a non-terminal progress checkpoint and the flow's real outcome is still in |
| | | 17 | | /// flight. |
| | | 18 | | /// <para> |
| | | 19 | | /// This is consulted exclusively when a response arrives with no live waiter (typically after a |
| | | 20 | | /// redeploy): the recovering process has the persisted recovery state and the payload, but not |
| | | 21 | | /// the original waiter — so the decision must be reconstructible from the payload alone. |
| | | 22 | | /// <see cref="RecoveryAction.Resume"/> routes to the resume callback |
| | | 23 | | /// (<c>OnLostSubscriberResume</c>) and <see cref="RecoveryAction.Fail"/> to the failure |
| | | 24 | | /// callback (<c>OnLostSubscriberFailure</c>, wrapped in an |
| | | 25 | | /// <see cref="AsyncResponseDomainFailureException"/>); both consume the recovery registration. |
| | | 26 | | /// <see cref="RecoveryAction.KeepWaiting"/> invokes nothing and <em>retains</em> the |
| | | 27 | | /// registration, so the terminal response that follows still routes — the recovery-side mirror |
| | | 28 | | /// of a live waiter's <c>Until</c> predicate observing and skipping a progress message. |
| | | 29 | | /// </para> |
| | | 30 | | /// <para> |
| | | 31 | | /// It has <strong>nothing to do with live completion</strong>: an active waiter decides when to |
| | | 32 | | /// stop with its <c>Until(...)</c> predicate and this method is never called on that path. The |
| | | 33 | | /// two answer different questions — <c>Until</c> asks "is the operation done?", this asks |
| | | 34 | | /// "what should this late result do to the flow?". |
| | | 35 | | /// </para> |
| | | 36 | | /// <para> |
| | | 37 | | /// The recovering process materializes the payload from the persisted registration's payload |
| | | 38 | | /// type before asking, and the chosen callback receives that same materialized instance — so |
| | | 39 | | /// <c>object</c>-, interface-, or base-typed callback parameters get the concrete payload, |
| | | 40 | | /// never raw broker JSON. |
| | | 41 | | /// </para> |
| | | 42 | | /// <para> |
| | | 43 | | /// The default returns <see cref="RecoveryAction.Fail"/> so that a payload never resumes a flow |
| | | 44 | | /// by omission — a failed response can never accidentally take the happy path. Override it only |
| | | 45 | | /// for payloads used with <see cref="IRecoverableAsyncResponseBuilder"/>. Durable channels |
| | | 46 | | /// (e.g. Redis) require the override when recovery callbacks are registered, and fail fast at |
| | | 47 | | /// waiter creation if it is missing. |
| | | 48 | | /// </para> |
| | | 49 | | /// </summary> |
| | 2 | 50 | | RecoveryAction OnRecovery() => RecoveryAction.Fail; |
| | | 51 | | } |