| | | 1 | | using System.Text.Json.Serialization; |
| | | 2 | | |
| | | 3 | | namespace AsyncResponse; |
| | | 4 | | |
| | | 5 | | /// <summary> |
| | | 6 | | /// A worker job offloaded for background execution: a serializable method-call description plus |
| | | 7 | | /// the correlation context to restore before executing it. |
| | | 8 | | /// </summary> |
| | | 9 | | public sealed class WorkerJobEnvelope |
| | | 10 | | { |
| | | 11 | | /// <summary> |
| | | 12 | | /// The wire schema version this job was written with. New jobs are always stamped with |
| | | 13 | | /// <see cref="WorkerJobEnvelopeSchema.Current"/>. The property is required on the wire; a missing |
| | | 14 | | /// or unsupported version is rejected so an incompatible producer cannot silently invoke the |
| | | 15 | | /// wrong method shape. |
| | | 16 | | /// </summary> |
| | | 17 | | [JsonRequired] |
| | 3 | 18 | | public int SchemaVersion { get; set; } = WorkerJobEnvelopeSchema.Current; |
| | | 19 | | |
| | | 20 | | /// <summary>The service method to execute.</summary> |
| | | 21 | | public required ReflectionCallDto Call { get; set; } |
| | | 22 | | |
| | | 23 | | /// <summary> |
| | | 24 | | /// The correlation id captured when the job was enqueued; restored into |
| | | 25 | | /// <see cref="AsyncResponseContext"/> before execution so downstream publishes correlate. |
| | | 26 | | /// </summary> |
| | | 27 | | public string? CorrelationId { get; set; } |
| | | 28 | | |
| | | 29 | | /// <summary> |
| | | 30 | | /// The reply target captured when the job was enqueued; restored into |
| | | 31 | | /// <see cref="AsyncResponseContext"/> before execution so downstream remote requests can |
| | | 32 | | /// publish responses to the same generic ingress. |
| | | 33 | | /// </summary> |
| | | 34 | | public AsyncResponseReplyTarget? ReplyTarget { get; set; } |
| | | 35 | | |
| | | 36 | | /// <summary> |
| | | 37 | | /// Serialized application ambient context captured when the job was enqueued (see |
| | | 38 | | /// <see cref="IAsyncResponseContextPropagator"/>), restored before the job executes when it is |
| | | 39 | | /// delivered through a broker ingress. <c>null</c> when no context propagators are registered. |
| | | 40 | | /// </summary> |
| | | 41 | | public Dictionary<string, string>? Context { get; set; } |
| | | 42 | | } |
| | | 43 | | |
| | | 44 | | /// <summary> |
| | | 45 | | /// Publishes worker jobs for background execution. Implement this against your message broker |
| | | 46 | | /// of choice for distributed execution (any consumer then feeds the message into |
| | | 47 | | /// <see cref="IAsyncResponseIngress.HandleWorkerMessageAsync"/>), or register the built-in |
| | | 48 | | /// in-memory queue (<c>AddAsyncResponse().WithInMemoryTransport()</c>) for development and |
| | | 49 | | /// single-node deployments. Application hosts should select a full transport package rather than |
| | | 50 | | /// raw-registering this interface directly. |
| | | 51 | | /// </summary> |
| | | 52 | | public interface IWorkerTransport |
| | | 53 | | { |
| | | 54 | | /// <summary>Publishes a worker job for asynchronous execution.</summary> |
| | | 55 | | Task PublishAsync(WorkerJobEnvelope job, CancellationToken cancellationToken = default); |
| | | 56 | | } |
| | | 57 | | |
| | | 58 | | /// <summary> |
| | | 59 | | /// Wire-schema version stamp for <see cref="WorkerJobEnvelope"/>. New jobs are stamped with |
| | | 60 | | /// <see cref="Current"/>. The ingress loader rejects (dead-letters) any job whose version is |
| | | 61 | | /// not explicitly supported: an unrecognized producer must never silently invoke an incompatible |
| | | 62 | | /// method shape. The JSON property is required. |
| | | 63 | | /// </summary> |
| | | 64 | | public static class WorkerJobEnvelopeSchema |
| | | 65 | | { |
| | | 66 | | /// <summary>The current wire schema version written by this build.</summary> |
| | | 67 | | public const int Current = 1; |
| | | 68 | | |
| | | 69 | | /// <summary> |
| | | 70 | | /// Returns <c>true</c> when a job with <paramref name="entryVersion"/> is safe to execute on |
| | | 71 | | /// this build. See <see cref="RecoveryStateSchema.IsReadable"/> for the policy. |
| | | 72 | | /// </summary> |
| | | 73 | | public static bool IsReadable(int entryVersion) |
| | | 74 | | => entryVersion == Current; |
| | | 75 | | } |