Fisheries VMS Domain · Lesson 18 of ∞ · Second pass · ← Lesson 17

Second pass · design practice, with a working precedent this time

Notification dispatch: for once, something real to copy

Lessons 15 through 17 found nothing to imitate. This one is different — a working, well-reasoned consumer already exists elsewhere in the codebase, built for a harder version of the same problem.

A real precedent: two consumers of the same subject, two different guarantees

EBoat.Gateway already has two background services consuming Subjects.TelemetryPosition, and they deliberately choose different halves of IEventBus:

public interface IEventBus
{
    Task PublishAsync<T>(string subject, T payload, CancellationToken ct = default);
    IAsyncEnumerable<T> SubscribeAsync<T>(string subject, string durableName, CancellationToken ct = default);
    IAsyncEnumerable<IEventMessage<T>> SubscribeWithAckAsync<T>(string subject, string durableName, CancellationToken ct = default);
}

PositionConsumerService (durable name "map-projection") uses plain SubscribeAsync — no acknowledgement. PositionArchiveService (durable name "position-archive") uses SubscribeWithAckAsync, acknowledging only after a batch commits to TimescaleDB. Same subject, same broker, two different delivery guarantees — and the reason traces straight back to something this workspace already established: "Map state lives in memory; history lives in the database." Losing one position update from the live map projection is harmless — the next update seconds later supersedes it. Losing one from permanent history is a real loss. The guarantee matches what's actually at stake, not a blanket default.

The buffering pattern, and why it matters more here

PositionArchiveService.ExecuteAsync reads from the broker into a bounded Channel<IEventMessage<PositionRecord>>, decoupling the fast broker read loop from the slower batched DB write on a separate task. That decoupling matters even more for notifications: an SMTP send or an SMS gateway call is slower and less reliable than a local database insert. Blocking the broker-read loop on a live network call to an external provider would be a worse mistake here than it would be for archiving.

The retry philosophy already established — and it isn't Polly

It would be easy to assume the "correct" .NET answer here is Polly, the standard resilience library for exactly this kind of transient-failure handling. It isn't referenced anywhere in this solution — not once, across all ten projects. The pattern that is established, in PositionArchiveService.WriteBatchAsync, is hand-rolled and worth reading exactly:

if (attempt >= 3)
{
    // Left unacknowledged on purpose: JetStream redelivers after
    // AckWait, so the positions are not lost by giving up here.
    logger.LogError(ex, "Failed to archive {Count} positions after {Attempts} attempts; " +
        "leaving them unacknowledged for redelivery.", rows.Count, attempt);
    return;
}

Three quick manual retries with a linear delay, then a deliberate give-up — not because the data is abandoned, but because NatsEventBus configures AckWait = TimeSpan.FromMinutes(1) on ack-based subscriptions: JetStream itself will redeliver an unacknowledged message after that window. The retry strategy here is genuinely two-tiered: a few fast in-process attempts for the kind of hiccup that resolves in milliseconds, then trust the broker's own slower redelivery cycle as the real retry mechanism, rather than building an elaborate in-process backoff ladder to do the same job twice. A SmtpChannel.SendAsync implementation should follow the identical shape: catch transient SMTP failures, a few quick retries, then let the exception propagate so the dispatcher doesn't ack — permanent failures (invalid recipient, auth failure) shouldn't retry at all and should fail fast instead, the same transient-vs-permanent split general retry practice recommends.

A structural gap the delivery model itself creates

At-least-once delivery (JetStream's actual guarantee, per its own docs) means a redelivered message is a normal, expected event, not a bug — and that has a direct consequence for NotificationMessage:

public sealed record NotificationMessage
{
    public required string Recipient { get; init; }
    public required string Subject { get; init; }
    public required string Body { get; init; }
    public required NotificationSeverity Severity { get; init; }
    public Guid? RelatedViolationId { get; init; }
}

There's no id field on this record at all. If the dispatcher retries after a redelivery — the exact scenario AckWait exists to handle — nothing distinguishes "this is a fresh notification" from "this is the same one, delivered again because the last ack was lost in transit, not because the send actually failed." Without a stable idempotency key, a redelivered Critical violation alert can page an inspector twice. This isn't a hypothetical design nicety; it's a structural requirement created by the specific delivery guarantee (SubscribeWithAckAsync) already argued for above — the two decisions have to be made together, not the channel guarantee first and the message shape as an afterthought.

Sketching the three channels

Messengers: a real, named gate, not an oversight

The optional messenger channels (Telegram Bot API, Viber Business Messages, Signal) aren't simply unbuilt like everything else in this lesson — they're explicitly gated on КСЗІ approval per assumption A-1, and not assumed enabled at go-live at all. КСЗІ is the Ukrainian information-security certification regime touched in Lesson 11's sovereignty discussion. The stated fallback is clean: if КСЗІ blocks every messenger channel, the baseline stack (email, SMS, in-app inbox) alone still satisfies ToR §5.11 — this is a case where "not built" is a pending policy gate, not an engineering gap at all.

A third citation drift

Both NotificationDispatcherService.cs and INotificationChannel.cs cite "assumption A-01." The tender's own assumptions register has no entry by that id — the actual row is A-1 (no leading zero). This is the third time this lesson series has found a code comment's citation not matching its source exactly — after the unresolved "risk 3.3.3(1)" in Lesson 17 and the bare, narrative-free compliance-matrix rows in Lesson 14. Three instances is a pattern, not a coincidence — worth raising as a standing practice question (a lint step checking that cited ids actually resolve, perhaps) rather than fixing each occurrence individually as it's found.

The dispatch flow, sketched

eboat.notifications (NATS, durable "notification-dispatch")
   │  SubscribeWithAckAsync<NotificationMessage>  ◀── at-least-once; needs the id field above
   ▼
bounded Channel<IEventMessage<NotificationMessage>>   ◀── decouples broker read from slow I/O
   │
   ▼
for each enabled INotificationChannel:
   SendAsync(message)  ── SmtpChannel / SmsChannel / InAppInboxChannel
   │   transient failure → a few quick retries, then throw
   │   permanent failure → fail fast, no retry
   ▼
ack only once required channels have succeeded   ◀── open question, see below

What would need to be built

• A stable id on NotificationMessage, and idempotency handling in each channel keyed on it — required by the at-least-once delivery model, not optional polish.
• NotificationDispatcherService.ExecuteAsync actually consuming eventBus.SubscribeWithAckAsync<NotificationMessage>, following PositionArchiveService's bounded-channel-plus-batch shape.
• SmtpChannel — a mail package, bound SMTP options, transient/permanent error classification.
• SmsChannel — an HTTP client against TurboSMS/Kyivstar (or the state gateway), with an API key in config.
• InAppInboxChannel — a persistence entity, plus a new per-user-group SignalR hub (not an extension of PositionsHub).
• A decided policy for partial multi-channel delivery failure before any of the above ships.

Check your recall

Something unclear, or want to go deeper on any term here? Ask the agent that built this lesson — it's your teacher for this workspace, not just a lesson generator.