Design a Notification Service (LLD)
"Design a notification service" is one of the most common LLD prompts at product companies, because every product has one and most of them have been rewritten at least once. In a system design round the same words lead to Kafka topics, provider fleets and a per-region fan-out tier. That version lives in Design a Notification System. In an LLD round the interviewer wants something smaller and more exact: the classes, the rules, and the code that decides whether, when, how and how many times a message reaches a person.
The domain looks thin. A notification is a message, a user and a channel. The difficulty is in the rules that pile up around that core. Users opt out of some things on some channels. Nobody wants a promotional SMS at 3 a.m. their local time. A bug in a caller must not send the same "your order shipped" email nine times. Providers time out, tokens expire, and an SMS gateway goes down for twenty minutes. Each rule is easy alone. The design question is where each one lives so that adding the twelfth rule doesn't mean editing the first eleven.
This page builds the service in the order you'd build it in an interview: requirements, entities, diagrams, patterns, then complete code in three languages with a self-checking main. After that come concurrency, three extensions an interviewer is likely to ask for, a test suite, common mistakes and follow-up questions with answers. Every code sample on this page was compiled and run.
1. Clarifying questions and requirements
Spend the first five minutes narrowing the prompt. The LLD interview framework explains why. Here are the questions worth asking, with the answers this design assumes.
| Question | Answer we assume | Why it matters |
|---|---|---|
| Who calls the service? | Other services in the same process, through submit(request). | Decides the API shape. No HTTP layer, no auth. |
| Which channels? | Email, SMS, mobile push, and an in-app inbox. More will come. | Channels must be pluggable, so a sender interface. |
| Is the content fixed or templated? | Templates with named variables, one variant per channel. An SMS is shorter than an email. | Rendering is per channel, and a missing variable must fail early. |
| Can users opt out? | Yes, per category (orders, marketing, security) and per channel, or a whole category at once. | A filter that can drop channels or the whole notification. |
| Quiet hours? | Each user may set a quiet window, such as 22:00 to 07:00, in their own time zone. Non-urgent messages wait until the window ends. Critical ones (OTPs, security alerts) go through. | Time-zone arithmetic, deferral, and a priority flag. |
| Rate limits? | Per user: at most N non-critical notifications per rolling hour. Excess ones are dropped and recorded. | A per-user sliding window. |
| What if the caller retries? | Each request carries an idempotency key. The same key never produces a second send. | An atomic check-and-insert, plus a provider-level dedup key. |
| What if a provider fails? | Retry transient errors with exponential backoff, up to a limit. Then fall back to the next channel the caller listed. Permanent errors skip straight to the fallback. | Two error kinds, a retry loop, a channel loop. |
| Do we track delivery? | Yes. Every notification has a status: queued, sent, delivered or failed, plus scheduled and suppressed. Providers report delivery asynchronously through receipts. | A state machine with legal transitions only. |
| Sync or async? | submit returns at once with a record. Sending happens on a bounded worker pool. | Producer-consumer, and a way to wait for idle in tests. |
| Persistence? | In memory. Say that a real system would store the records and the idempotency keys in a database. | Keeps us in LLD. |
Functional requirements
submit(request)takes an idempotency key, a user id, a template id, template variables, a category, an ordered list of channels, and a priority. It returns aNotificationrecord immediately.- Validation happens before anything is stored. An unknown user or template, an empty channel list, a channel the template has no variant for, or a missing variable is rejected with an error.
- A second
submitwith the same key returns the original record and sends nothing. The same key with a different request is an error. - Preferences remove opted-out channels. If none are left, the notification is suppressed with a reason.
- During the user's quiet hours a non-critical notification is scheduled for the end of the window, computed in the user's time zone, including daylight-saving changes. A ticker calls
releaseDue()to send it later, and the preferences are checked again at that point. - More than N non-critical notifications per user per rolling window are suppressed as rate limited.
- Sending tries the channels in order. Each channel gets up to
maxAttemptstries with exponential backoff for transient errors. A permanent error moves to the next channel at once. When every channel is exhausted the notification fails. - A delivery receipt moves a sent notification to delivered or failed. Duplicate receipts are ignored, and a receipt that arrives before the worker has recorded the send is not lost.
- Status changes follow a fixed state machine. An illegal transition raises an error.
Non-functional requirements
- Thread-safe. Many callers submit at once, and several workers send at once.
- Never sends twice for one key, even when two threads submit the same key in the same microsecond.
- Bounded threads. A fixed worker pool, not a thread per notification.
- Testable without waiting. The clock, the sleep function and the providers are injected, so tests run in milliseconds and never call a real provider.
- Open for extension. A new channel or a new rule is a new class, not an edit to the service.
Out of scope
Persistence, the HTTP API, provider SDKs, a user-facing preference UI, analytics, localisation of templates, and multi-region delivery. If the interviewer pushes on any of them, name where it would plug in and move on.
2. Core entities and relationships
Start from the nouns in the requirements, as From Nouns to Classes describes, and give each one a single job.
| Entity | Responsibility | Notes |
|---|---|---|
NotificationService | The facade. Validates, enforces idempotency, runs the filters, hands work to the pool, accepts receipts. | The only class callers use. |
Request | What the caller asked for. Immutable. | Immutability is what lets us compare a retried request with the original. |
Notification | One delivery record: status, history, attempts, the channel that worked, the reason it was suppressed or failed. | Owns its own lock and its own state machine. |
Status | The lifecycle states and the table of legal transitions. | An enum with data, not a class per state. See the patterns section. |
User | Id, time zone, address per channel, opt-outs, optional quiet hours. | Preferences live on the user because they are about the user. |
QuietHours | A start and end time of day, possibly wrapping midnight. | A value object with one method, contains(time). |
Template | An id and one subject and body per channel, with {variable} placeholders. | render(channel, values) fails on a missing variable. |
Message | A rendered subject and body. | What a sender actually sends. |
Sender | The channel strategy: send(address, message, dedupKey). | One implementation per channel, plus fakes for tests. |
Filter | One rule: look at a notification and return pass, suppress or defer. | Preferences, quiet hours and rate limiting are three filters. |
Decision | The result of a filter. | A tiny value type with three cases. |
Relationships:
- The service has many templates, users, senders (one per channel) and filters (in order).
- A
Requestrefers to one user and one template by id. - A
Notificationwraps exactly oneRequest, oneUser, and the list of channels still allowed after filtering. - Each
Senderis keyed by aChannelvalue. The service never knows which concrete class is behind a channel.
Three modelling decisions shape everything that follows.
The record exists before the decision. The service creates the Notification as soon as the idempotency key is accepted, and then runs the filters. A suppressed notification is still a record, with a reason. That lets support staff answer "why didn't I get the email?" with "you opted out of marketing email on 3 March", and it means a retried request for a suppressed notification gets the same answer instead of a second chance.
Channels are an ordered list, not a single value. The caller says "push, then SMS". Filters narrow the list, and the delivery loop walks it. Fallback falls out of the data structure instead of needing its own subsystem.
Errors come in two kinds. A TransientError means "try again later": a timeout, a 503, throttling. A PermanentError means "this channel will never work for this message": an invalid phone number, an unregistered push token. The kind decides whether we spend retries or move on, and getting it wrong in either direction is costly. Retrying a dead token three times wastes seconds of a worker. Giving up on a timeout loses a message that would have gone through on the next try.
3. Class diagram
classDiagram
class NotificationService {
-byKey: map of key to Notification
-byId: map of id to Notification
-scheduled: list of Notification
-pending: int
-pool: worker pool
+submit(request) Notification
+releaseDue() int
+onReceipt(id, delivered)
+awaitIdle(timeout) boolean
-admit(notification)
-deliver(notification)
}
class Request {
<<immutable>>
+idempotencyKey: String
+userId: String
+templateId: String
+values: map
+category: String
+channels: list of Channel
+priority: Priority
}
class Notification {
+id: String
+status: Status
+history: list of Status
+channels: list of Channel
+attempts: list of String
+notBefore: Instant
+move(to, reason)
+markSent(channel)
+receipt(delivered)
}
class Status {
<<enumeration>>
QUEUED
SCHEDULED
SENDING
RETRYING
SENT
DELIVERED
FAILED
SUPPRESSED
+canMoveTo(next) boolean
}
class User {
+id: String
+zone: ZoneId
+addresses: map of Channel to String
+optOuts: set of String
+quiet: QuietHours
}
class Template {
+id: String
+render(channel, values) Message
}
class Sender {
<<interface>>
+send(address, message, dedupKey)
}
class Filter {
<<interface>>
+check(notification, now) Decision
}
class PreferenceFilter
class QuietHoursFilter
class RateLimitFilter {
-limit: int
-window: Duration
-log: map of user to timestamps
}
class FakeSender {
+outbox: list of Message
+fail(error, times)
}
class InAppSender {
+inbox: map of user to messages
}
NotificationService "1" o-- "*" Notification
NotificationService --> "*" Filter : runs in order
NotificationService --> "*" Sender : one per channel
NotificationService --> "*" Template
Notification --> Request
Notification --> User
Notification --> Status
Filter <|.. PreferenceFilter
Filter <|.. QuietHoursFilter
Filter <|.. RateLimitFilter
Sender <|.. FakeSender
Sender <|.. InAppSender
What's missing on purpose:
- No
EmailNotification,SmsNotificationsubclasses. The channel is data on the record and behaviour in the sender. A notification that falls back from push to SMS would otherwise have to change class halfway through its life. - No
NotificationFactory. There's one kind of notification. A factory with one product is ceremony. - No
PreferenceService. Preferences are a field onUserand one filter that reads it. If preferences grew complex (per-device settings, digests, frequency caps per category) they'd earn their own class. Not yet. - No real email or SMS sender. In the interview you name the interface and the fake. A real
SesEmailSenderis an adapter around a vendor SDK and adds nothing to the design discussion.
4. Key flows
Submit and deliver: the happy path
sequenceDiagram
actor C as Caller
participant S as NotificationService
participant F as Filter chain
participant P as Worker pool
participant X as Email sender
actor R as Provider webhook
C->>S: submit(request with key k1)
S->>S: validate user, template and variables
S->>S: lock, key k1 unseen, store new record, unlock
S->>F: preferences, quiet hours, rate limit
F-->>S: pass, channels narrowed to email
S->>P: submit deliver(n1)
S-->>C: n1 with status QUEUED
P->>S: deliver(n1) moves it to SENDING
S->>X: send(address, rendered message, n1 email key)
X-->>S: accepted
S->>S: n1 moves to SENT
R->>S: onReceipt(n1, delivered)
S->>S: n1 moves to DELIVERED
The caller gets its answer before any provider is called. That's the point of the pool: a slow SMS gateway must not slow down the checkout service that asked for the SMS.
Retry, then fall back to another channel
sequenceDiagram
participant W as Worker
participant N as Notification n7
participant PU as Push sender
participant SM as SMS sender
W->>N: SENDING
W->>PU: attempt 1
PU-->>W: TransientError timeout
W->>N: RETRYING
W->>W: sleep 500 ms
W->>N: SENDING
W->>PU: attempt 2
PU-->>W: PermanentError token not registered
Note over W: permanent, so stop spending push retries
W->>SM: attempt 1 on the next channel
SM-->>W: accepted
W->>N: SENT via SMS
Two loops, nested. The outer loop walks channels, and the inner loop spends retries on one channel. A permanent error breaks the inner loop early. Only when the outer loop runs out does the notification fail.
Quiet hours: defer, then release
sequenceDiagram
actor C as Caller
participant S as NotificationService
participant Q as QuietHoursFilter
participant T as Ticker
C->>S: submit for asha at 17.00 UTC
S->>Q: check(n9, now)
Q->>Q: 17.00 UTC is 22.30 in Asia/Kolkata, inside 22.00 to 07.00
Q-->>S: defer until 07.00 IST, which is 01.30 UTC
S->>S: n9 moves to SCHEDULED, add to scheduled list
S-->>C: n9 with status SCHEDULED
T->>S: releaseDue() at 01.00 UTC
S-->>T: 0 released
T->>S: releaseDue() at 01.30 UTC
S->>S: n9 moves back to QUEUED
S->>Q: run the whole chain again
Q-->>S: pass
S->>S: hand n9 to the worker pool
Running the whole chain again on release matters. In the eight hours the message waited, the user may have opted out, or the rate-limit window may have filled up. A deferred notification is a new decision later, not a decision already made.
A receipt that beats the worker
Providers call webhooks from their own threads. Nothing guarantees the webhook arrives after our worker has recorded the send.
sequenceDiagram
participant W as Worker thread
participant N as Notification
participant X as Provider
actor H as Webhook thread
W->>X: send(...)
X->>H: delivered, fired immediately
H->>N: receipt(delivered)
N->>N: status is still SENDING, so remember the receipt
X-->>W: send returns
W->>N: markSent(email)
N->>N: SENT, then apply the remembered receipt
N->>N: DELIVERED
A naive receipt() that only accepts receipts in SENT would throw an illegal-transition error here, or silently drop the receipt, and the notification would sit in SENT forever. Buffering one early receipt on the record costs one nullable field.
The delivery state machine
stateDiagram-v2
[*] --> QUEUED: key accepted
QUEUED --> SUPPRESSED: opted out or rate limited
QUEUED --> SCHEDULED: quiet hours
SCHEDULED --> QUEUED: releaseDue
QUEUED --> SENDING: worker picks it up
SENDING --> RETRYING: transient error, attempts left
RETRYING --> SENDING: after backoff
SENDING --> SENT: provider accepted
SENDING --> FAILED: every channel exhausted
SENT --> DELIVERED: delivery receipt
SENT --> FAILED: bounce receipt
DELIVERED --> [*]
FAILED --> [*]
SUPPRESSED --> [*]
SENT and DELIVERED are different facts. SENT means the provider accepted the message. DELIVERED means the provider says it reached the device or the mailbox. Many interview designs merge them, and then there's nowhere to record a bounce.
5. Patterns, why, and the alternatives rejected
Strategy for channels
Each channel has the same job, "deliver this rendered message to this address", done in a completely different way: an SMTP call, an SMS gateway API, an APNs or FCM push, a row in an inbox table. That's the textbook case for Strategy: one interface, send(address, message, dedupKey), and one class per channel. The service holds a map from channel to sender and never branches on the channel.
The payoff shows up in three places:
- New channels are new classes. WhatsApp, Slack, a webhook to a customer's endpoint: each is a sender plus a template variant. The service, the filters and the state machine don't change.
- Fakes for tests.
FakeSenderrecords what it was asked to send and can be scripted to fail: "throw a transient error twice, then succeed". Every retry and fallback rule is testable without a network and without sleeping. Designing for Testability covers why a fake beats a mock here. A fake has behaviour you can reason about, and the tests read as "the push provider is down" instead of "verifysendwas called with these arguments three times". - Decorators compose. Because a sender is a one-method interface, wrapping it is trivial. A circuit breaker, a logging sender or a per-provider rate limiter is a class that implements
Senderand holds anotherSender. Extension A below builds one.
Alternative rejected: a switch on channel inside the service. It works for two channels and turns into a 400-line method by the fifth. Each case drags in its own SDK imports, and you can't test the retry logic without also exercising every provider client.
Alternative rejected: an abstract BaseSender with retry logic in it. That's Template Method: the base class runs the retry loop and calls an abstract doSend. It looks tidy, but it puts retry policy in every channel's inheritance chain. Fallback across channels can't live there at all, because a sender only knows about itself. Keep the senders dumb and the policy in one place.
Chain of Responsibility for the rules
Preferences, quiet hours and rate limits are each "look at this notification and decide". They share a shape, and the list will grow: frequency caps per category, a global kill switch for an incident, do-not-disturb during a user's active call, regional regulations on SMS hours. So each rule is a Filter with one method returning a Decision, and the service runs them in order, stopping at the first one that suppresses or defers. That's Chain of Responsibility in its list form: the chain is a list held by the service rather than each handler holding a next pointer.
flowchart LR
IN["submit or releaseDue"] --> P["PreferenceFilter"]
P -->|"pass, channels narrowed"| Q["QuietHoursFilter"]
Q -->|"pass"| RL["RateLimitFilter"]
RL -->|"pass"| POOL["Worker pool"]
P -->|"no channels left"| SUP["SUPPRESSED"]
Q -->|"inside window"| SCH["SCHEDULED"]
RL -->|"over limit"| SUP
Why a list and not linked handlers: the order is configuration, and a list makes it visible in one line where the service is built. Linked handlers hide the order across constructors, and inserting a filter in the middle means rewiring two objects.
Order matters, and it's a design decision you should say out loud. Preferences go first, because there's no point deferring a message the user opted out of. Quiet hours go before rate limiting, so a message that's going to wait doesn't use up quota now. Rate limiting goes last, so only messages that are actually about to be sent count against the limit. Put the rate limiter first and a user who opted out of marketing would still have marketing messages eat their quota, which then blocks an order update they wanted.
Why not Decorator for filters? You could wrap the delivery function in a QuietHours(RateLimit(Preferences(deliver))) stack. Decorators fit when each layer adds behaviour around a call and then continues. Our filters mostly decide and then stop, and two of them produce outcomes (defer, suppress) that the service has to record in the state machine. A decision object that the service interprets keeps the state transitions in one place. Decorators are still the right tool one layer down, around senders, where every layer really does wrap the same call.
Why not Specification? A specification answers yes or no. Our rules have three outcomes, and "defer until 01:30 UTC" carries data. A specification would fit the opt-out rule alone, but forcing quiet hours into a boolean would push the "until when" computation back into the service.
A state machine as an enum with a transition table
The lifecycle has eight states. It's tempting to reach for the State pattern, with a class per state and methods like onSendSuccess() on each. Ask what the states actually do differently. Nothing: a notification in RETRYING doesn't behave differently from one in SENDING. The behaviour lives in the worker. What the states need is a guard that refuses illegal moves. A table from each state to its allowed next states does that in eight lines, and it's easy to print as the state diagram above.
| Approach | When it fits | Here |
|---|---|---|
| Enum plus transition table | States are labels with rules about order | ✅ Chosen |
| State pattern, one class per state | Each state handles the same events differently, like a vending machine's insertCoin | Rejected: no per-state behaviour |
Boolean flags (sent, delivered, failed) | Never | Allows sent=false, delivered=true, which is nonsense |
| Free-form status string | Never | No guard at all |
The guard earns its keep on exactly the bugs that are hard to see in review. A receipt handler that moves a record straight from SENDING to DELIVERED looks harmless, and the table refuses it on the first test run. Thinking about why it was refused is what leads to the early-receipt buffer described in the flows above.
Idempotency key with an atomic insert
There's no GoF name for this, but it's the most important pattern on the page. The caller supplies a key that identifies the intent, such as order-shipped:A1. The service stores key → record, and a second submit with the same key returns the first record. Two details make it correct:
- The check and the insert are one atomic step. "If the key is missing, insert it" under a lock, or
putIfAbsenton a concurrent map. A separatecontainsKeyfollowed byputlets two threads both see "missing" and both send. - The stored request is compared with the new one. Same key, different body almost always means a caller bug, such as a key built from the user id alone. Returning the old record silently would hide it. Stripe's API does the same: reusing a key with different parameters is an error.
The service also passes a dedup key to the provider: the notification id plus the channel. If our process crashes after the provider accepted a message but before we recorded SENT, a recovery job will try again, and a provider that supports idempotency (many email and push APIs do) drops the duplicate. That covers the one gap an in-process key can't. Idempotency and idempotent consumers go deeper.
Producer-consumer with a worker pool
submit is the producer and the pool's threads are the consumers. That gives three things: callers don't wait for providers, the number of threads is fixed no matter how many notifications arrive, and a burst queues up rather than spawning threads. Concurrency Patterns in LLD covers the general shape. In TypeScript there are no threads, so the "pool" is a counter of in-flight async deliveries with a cap. It's the same pattern with promises.
Patterns deliberately not used
- Observer for status changes. It's a natural extension ("notify analytics when a message is delivered"), but nothing in the requirements needs it. Add a listener list to the service when someone asks.
- Singleton service. Tests build a fresh service per test with fake senders. A singleton would make that impossible.
- Builder for requests. A real API would have one, because
Requesthas seven fields. In an interview, a constructor or a helper likereq(key, ...)in tests is fine, and you can mention the builder in one sentence.
6. The code
All three versions implement the same design. Each ends with a demo that checks every rule: rendering, receipts, idempotency under eight concurrent threads, opt-outs, a missing variable, retries with doubling backoff, fallback on a permanent error, exhaustion, quiet hours in Kolkata, a daylight-saving boundary in New York, rate limiting, an early receipt, and an illegal transition.
- Java 24:
javac NotifyDemo.java && java NotifyDemo. - Python 3.12: save as
notify.py, thenpython notify.py. The tests and extensions below import it. On Windows,zoneinfoneeds thetzdatapackage (pip install tzdata). - TypeScript: save as
notify.tsin a folder with"type": "module"inpackage.json, thennpx tsx notify.ts. It typechecks undertsc --strict --target es2022 --module nodenextwith@types/node.
// NotifyDemo.java -> javac NotifyDemo.java && java -ea NotifyDemo
import java.time.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Consumer;
import java.util.function.Supplier;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
enum Channel { EMAIL, SMS, PUSH, IN_APP }
enum Priority { NORMAL, CRITICAL }
enum Status {
QUEUED, SCHEDULED, SENDING, RETRYING, SENT, DELIVERED, FAILED, SUPPRESSED;
private static final Map<Status, Set<Status>> ALLOWED = new EnumMap<>(Status.class);
static {
ALLOWED.put(QUEUED, EnumSet.of(SENDING, SCHEDULED, SUPPRESSED));
ALLOWED.put(SCHEDULED, EnumSet.of(QUEUED));
ALLOWED.put(SENDING, EnumSet.of(SENT, RETRYING, FAILED));
ALLOWED.put(RETRYING, EnumSet.of(SENDING));
ALLOWED.put(SENT, EnumSet.of(DELIVERED, FAILED));
for (Status s : List.of(DELIVERED, FAILED, SUPPRESSED)) ALLOWED.put(s, EnumSet.noneOf(Status.class));
}
boolean canMoveTo(Status to) { return ALLOWED.get(this).contains(to); }
}
class IllegalTransition extends RuntimeException { IllegalTransition(String m) { super(m); } }
class IdempotencyConflict extends RuntimeException { IdempotencyConflict(String m) { super(m); } }
class TransientError extends RuntimeException { TransientError(String m) { super(m); } }
class PermanentError extends RuntimeException { PermanentError(String m) { super(m); } }
record QuietHours(LocalTime start, LocalTime end) {
boolean contains(LocalTime t) {
if (!start.isAfter(end)) return !t.isBefore(start) && t.isBefore(end);
return !t.isBefore(start) || t.isBefore(end); // wraps midnight
}
}
final class User {
final String id; final ZoneId zone; final Map<Channel, String> addresses;
final Set<String> optOuts = ConcurrentHashMap.newKeySet(); // "marketing:SMS" or "marketing:*"
final QuietHours quiet;
User(String id, String zone, Map<Channel, String> addresses, QuietHours quiet) {
this.id = id; this.zone = ZoneId.of(zone); this.addresses = addresses; this.quiet = quiet;
}
}
record Message(String subject, String body) {}
final class Template {
private static final Pattern VAR = Pattern.compile("\\{(\\w+)\\}");
final String id; private final Map<Channel, String[]> variants;
Template(String id, Map<Channel, String[]> variants) { this.id = id; this.variants = variants; }
Message render(Channel ch, Map<String, String> values) {
String[] v = variants.get(ch);
if (v == null) throw new IllegalArgumentException("template " + id + " has no " + ch + " variant");
return new Message(fill(v[0], values), fill(v[1], values));
}
private String fill(String text, Map<String, String> values) {
Matcher m = VAR.matcher(text);
StringBuilder out = new StringBuilder();
while (m.find()) {
String value = values.get(m.group(1));
if (value == null) throw new IllegalArgumentException("template " + id + " needs variable '" + m.group(1) + "'");
m.appendReplacement(out, Matcher.quoteReplacement(value));
}
return m.appendTail(out).toString();
}
}
record Request(String idempotencyKey, String userId, String templateId, Map<String, String> values,
String category, List<Channel> channels, Priority priority) {}
final class Notification {
private static final AtomicInteger IDS = new AtomicInteger();
final String id = "n" + IDS.incrementAndGet();
final Request request; final User user;
volatile List<Channel> channels;
private Status status = Status.QUEUED;
final List<Status> history = new ArrayList<>(List.of(Status.QUEUED));
final List<String> attempts = Collections.synchronizedList(new ArrayList<>());
volatile Channel channel; volatile Instant notBefore; volatile String reason;
private Boolean earlyReceipt;
Notification(Request request, User user) {
this.request = request; this.user = user; this.channels = List.copyOf(request.channels());
}
synchronized Status status() { return status; }
synchronized List<Status> history() { return List.copyOf(history); }
synchronized void move(Status to, String why) {
if (!status.canMoveTo(to)) throw new IllegalTransition(id + ": " + status + " -> " + to);
status = to; history.add(to);
if (why != null) reason = why;
}
synchronized void markSent(Channel ch) {
channel = ch; move(Status.SENT, null);
if (earlyReceipt != null) applyReceipt(earlyReceipt); // the receipt beat us here
}
synchronized void receipt(boolean delivered) {
if (status == Status.SENDING || status == Status.RETRYING) earlyReceipt = delivered;
else if (status == Status.SENT) applyReceipt(delivered);
// DELIVERED or FAILED already: duplicate receipt, ignore
}
private void applyReceipt(boolean delivered) {
move(delivered ? Status.DELIVERED : Status.FAILED, delivered ? null : "bounced");
}
}
// ---------- channels (Strategy) ----------
interface Sender { void send(String address, Message message, String dedupKey); }
final class FakeSender implements Sender {
final List<Message> outbox = Collections.synchronizedList(new ArrayList<>());
private final Deque<Supplier<RuntimeException>> script = new ArrayDeque<>();
private final Consumer<String> onSend;
FakeSender() { this(k -> {}); }
FakeSender(Consumer<String> onSend) { this.onSend = onSend; }
synchronized FakeSender fail(Supplier<RuntimeException> error, int times) {
for (int i = 0; i < times; i++) script.add(error);
return this;
}
public void send(String address, Message message, String dedupKey) {
synchronized (this) {
if (!script.isEmpty()) throw script.poll().get();
outbox.add(message);
}
onSend.accept(dedupKey);
}
}
final class InAppSender implements Sender {
final Map<String, List<Message>> inbox = new ConcurrentHashMap<>();
public void send(String address, Message message, String dedupKey) {
inbox.computeIfAbsent(address, k -> Collections.synchronizedList(new ArrayList<>())).add(message);
}
}
// ---------- filters (Chain of Responsibility) ----------
record Decision(String kind, String reason, Instant until) {
static final Decision PASS = new Decision("pass", null, null);
static Decision suppress(String why) { return new Decision("suppress", why, null); }
static Decision defer(String why, Instant until) { return new Decision("defer", why, until); }
}
interface Filter { Decision check(Notification n, Instant now); }
final class PreferenceFilter implements Filter {
public Decision check(Notification n, Instant now) {
String cat = n.request.category();
Set<String> outs = n.user.optOuts;
n.channels = n.channels.stream()
.filter(c -> !outs.contains(cat + ":*") && !outs.contains(cat + ":" + c) && n.user.addresses.containsKey(c))
.toList();
return n.channels.isEmpty() ? Decision.suppress("opted out or no address") : Decision.PASS;
}
}
final class QuietHoursFilter implements Filter {
static Instant quietEnd(QuietHours q, Instant now, ZoneId zone) {
ZonedDateTime local = now.atZone(zone);
LocalDate day = local.toLocalTime().isBefore(q.end()) ? local.toLocalDate() : local.toLocalDate().plusDays(1);
return ZonedDateTime.of(day, q.end(), zone).toInstant(); // DST-aware: the zone rules decide the offset
}
public Decision check(Notification n, Instant now) {
QuietHours q = n.user.quiet;
if (q == null || n.request.priority() == Priority.CRITICAL) return Decision.PASS;
if (!q.contains(now.atZone(n.user.zone).toLocalTime())) return Decision.PASS;
return Decision.defer("quiet hours", quietEnd(q, now, n.user.zone));
}
}
final class RateLimitFilter implements Filter {
private final int limit; private final Duration window;
private final Map<String, Deque<Instant>> log = new HashMap<>();
RateLimitFilter(int limit, Duration window) { this.limit = limit; this.window = window; }
public synchronized Decision check(Notification n, Instant now) {
if (n.request.priority() == Priority.CRITICAL) return Decision.PASS;
Deque<Instant> times = log.computeIfAbsent(n.user.id, k -> new ArrayDeque<>());
while (!times.isEmpty() && !times.peekFirst().isAfter(now.minus(window))) times.pollFirst();
if (times.size() >= limit) return Decision.suppress("rate limited");
times.addLast(now);
return Decision.PASS;
}
}
// ---------- the service ----------
interface Sleeper { void sleep(Duration d) throws InterruptedException; }
final class NotificationService {
final Map<String, User> users; final Map<String, Template> templates; final Map<Channel, Sender> senders;
private final List<Filter> filters; private final Supplier<Instant> clock; private final Sleeper sleeper;
private final int maxAttempts; private final Duration backoff;
private final Map<String, Notification> byKey = new HashMap<>(), byId = new HashMap<>();
private final List<Notification> scheduled = new ArrayList<>();
private int pending = 0;
private final ExecutorService pool;
NotificationService(Map<String, User> users, Map<String, Template> templates, Map<Channel, Sender> senders,
List<Filter> filters, Supplier<Instant> clock, Sleeper sleeper,
int maxAttempts, Duration backoff, int workers) {
this.users = users; this.templates = templates; this.senders = senders; this.filters = filters;
this.clock = clock; this.sleeper = sleeper; this.maxAttempts = maxAttempts; this.backoff = backoff;
this.pool = Executors.newFixedThreadPool(workers);
}
Notification submit(Request req) {
User user = users.get(req.userId());
Template template = templates.get(req.templateId());
if (user == null || template == null) throw new IllegalArgumentException("unknown user or template");
if (req.channels().isEmpty()) throw new IllegalArgumentException("at least one channel is required");
for (Channel ch : req.channels()) template.render(ch, req.values()); // fail fast
Notification n;
synchronized (this) { // check-and-insert is one atomic step
Notification existing = byKey.get(req.idempotencyKey());
if (existing != null) {
if (!existing.request.equals(req))
throw new IdempotencyConflict("key " + req.idempotencyKey() + " reused with a different request");
return existing;
}
n = new Notification(req, user);
byKey.put(req.idempotencyKey(), n);
byId.put(n.id, n);
}
admit(n);
return n;
}
synchronized boolean hasKey(String key) { return byKey.containsKey(key); }
synchronized Notification get(String id) { return byId.get(id); }
private void admit(Notification n) {
Instant now = clock.get();
for (Filter f : filters) {
Decision d = f.check(n, now);
if (d.kind().equals("suppress")) { n.move(Status.SUPPRESSED, d.reason()); return; }
if (d.kind().equals("defer")) {
n.notBefore = d.until();
n.move(Status.SCHEDULED, d.reason());
synchronized (this) { scheduled.add(n); }
return;
}
}
synchronized (this) { pending++; }
pool.submit(() -> deliver(n));
}
int releaseDue() {
Instant now = clock.get();
List<Notification> due = new ArrayList<>();
synchronized (this) {
for (Iterator<Notification> it = scheduled.iterator(); it.hasNext(); ) {
Notification n = it.next();
if (!n.notBefore.isAfter(now)) { due.add(n); it.remove(); }
}
}
for (Notification n : due) { n.move(Status.QUEUED, null); admit(n); }
return due.size();
}
private void deliver(Notification n) {
try {
n.move(Status.SENDING, null);
Template template = templates.get(n.request.templateId());
for (Channel ch : n.channels) {
Sender sender = senders.get(ch);
for (int attempt = 1; attempt <= maxAttempts; attempt++) {
try {
if (sender == null) throw new PermanentError("no sender configured");
sender.send(n.user.addresses.get(ch), template.render(ch, n.request.values()), n.id + ":" + ch);
n.markSent(ch);
return;
} catch (PermanentError e) {
n.attempts.add(ch + "#" + attempt + ": " + e.getMessage());
break; // fall back to the next channel
} catch (RuntimeException e) {
n.attempts.add(ch + "#" + attempt + ": " + e.getMessage());
if (attempt < maxAttempts) {
n.move(Status.RETRYING, null);
// Simplification: sleeps on the worker; a delay queue frees it (see task scheduler)
sleeper.sleep(backoff.multipliedBy(1L << (attempt - 1)));
n.move(Status.SENDING, null);
}
}
}
}
n.move(Status.FAILED, "all channels failed");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} finally {
synchronized (this) { pending--; notifyAll(); }
}
}
void onReceipt(String notificationId, boolean delivered) { get(notificationId).receipt(delivered); }
synchronized boolean awaitIdle(Duration timeout) throws InterruptedException {
long deadline = System.nanoTime() + timeout.toNanos();
while (pending > 0) {
long left = deadline - System.nanoTime();
if (left <= 0) return false;
wait(Math.max(1, left / 1_000_000));
}
return true;
}
void shutdown() { pool.shutdown(); }
}
// ---------- demo and checks ----------
final class FakeClock implements Supplier<Instant> {
volatile Instant now;
FakeClock(Instant now) { this.now = now; }
public Instant get() { return now; }
}
public class NotifyDemo {
static final List<Duration> sleeps = Collections.synchronizedList(new ArrayList<>());
static Map<Channel, Sender> senders;
static NotificationService build(FakeClock clock, int rateLimit) {
Map<String, User> users = new HashMap<>();
users.put("asha", new User("asha", "Asia/Kolkata", Map.of(Channel.EMAIL, "asha@example.com",
Channel.SMS, "+911", Channel.PUSH, "tok-a", Channel.IN_APP, "asha"),
new QuietHours(LocalTime.of(22, 0), LocalTime.of(7, 0))));
User ben = new User("ben", "America/New_York", Map.of(Channel.EMAIL, "ben@example.com",
Channel.SMS, "+12", Channel.PUSH, "tok-b"), null);
ben.optOuts.add("marketing:SMS");
users.put("ben", ben);
Map<String, Template> templates = Map.of(
"order_shipped", new Template("order_shipped", Map.of(
Channel.EMAIL, new String[]{"Order {order} shipped", "Hi {name}, order {order} is on its way."},
Channel.SMS, new String[]{"", "Order {order} shipped."},
Channel.PUSH, new String[]{"Shipped", "Order {order} is on its way"},
Channel.IN_APP, new String[]{"Shipped", "Order {order} is on its way"})),
"sale", new Template("sale", Map.of(
Channel.SMS, new String[]{"", "Sale: {pct}% off today"},
Channel.EMAIL, new String[]{"Sale", "Hi {name}, {pct}% off today"})));
senders = new EnumMap<>(Channel.class);
senders.put(Channel.EMAIL, new FakeSender());
senders.put(Channel.SMS, new FakeSender());
senders.put(Channel.PUSH, new FakeSender());
senders.put(Channel.IN_APP, new InAppSender());
List<Filter> filters = List.of(new PreferenceFilter(), new QuietHoursFilter(),
new RateLimitFilter(rateLimit, Duration.ofHours(1)));
return new NotificationService(users, templates, senders, filters, clock, sleeps::add,
3, Duration.ofMillis(500), 4);
}
static Request req(String key, String user, List<Channel> channels, String template, String category,
Priority priority, Map<String, String> extra) {
Map<String, String> values = new HashMap<>(Map.of("name", user.substring(0, 1).toUpperCase() + user.substring(1), "order", "A1"));
values.putAll(extra);
return new Request(key, user, template, Map.copyOf(values), category, channels, priority);
}
static Request req(String key, String user, Channel... channels) {
return req(key, user, List.of(channels), "order_shipped", "orders", Priority.NORMAL, Map.of());
}
static FakeSender fake(Channel c) { return (FakeSender) senders.get(c); }
static void check(boolean ok, String what) { if (!ok) throw new AssertionError(what); }
public static void main(String[] args) throws Exception {
Instant noon = Instant.parse("2026-11-10T12:00:00Z");
FakeClock clock = new FakeClock(noon);
NotificationService svc = build(clock, 100);
Duration t = Duration.ofSeconds(5);
// 1. happy path, then a delivery receipt (twice)
Notification n = svc.submit(req("k1", "ben", Channel.EMAIL));
check(svc.awaitIdle(t) && n.status() == Status.SENT, "sent");
check(fake(Channel.EMAIL).outbox.get(0).body().equals("Hi Ben, order A1 is on its way."), "rendered");
svc.onReceipt(n.id, true); svc.onReceipt(n.id, true);
check(n.history().equals(List.of(Status.QUEUED, Status.SENDING, Status.SENT, Status.DELIVERED)), "history");
// 2. idempotency under 8 threads
int before = fake(Channel.EMAIL).outbox.size();
ExecutorService ex = Executors.newFixedThreadPool(8);
List<Future<Notification>> fs = new ArrayList<>();
for (int i = 0; i < 8; i++) fs.add(ex.submit(() -> svc.submit(req("k2", "ben", Channel.EMAIL))));
Set<String> ids = new HashSet<>();
for (Future<Notification> f : fs) ids.add(f.get().id);
ex.shutdown();
check(svc.awaitIdle(t) && ids.size() == 1 && fake(Channel.EMAIL).outbox.size() == before + 1, "one send");
try {
svc.submit(req("k2", "ben", List.of(Channel.EMAIL), "order_shipped", "orders", Priority.NORMAL, Map.of("order", "B2")));
throw new IllegalStateException("conflict expected");
} catch (IdempotencyConflict expected) {}
// 3. opt-outs
n = svc.submit(req("k3", "ben", List.of(Channel.SMS, Channel.EMAIL), "sale", "marketing", Priority.NORMAL, Map.of("pct", "20")));
check(svc.awaitIdle(t) && n.channel == Channel.EMAIL, "sms opted out");
svc.users.get("ben").optOuts.add("marketing:*");
n = svc.submit(req("k4", "ben", List.of(Channel.EMAIL), "sale", "marketing", Priority.NORMAL, Map.of("pct", "20")));
check(n.status() == Status.SUPPRESSED, "suppressed");
// 4. missing variable
try {
svc.submit(new Request("k5", "ben", "order_shipped", Map.of("name", "Ben"), "orders", List.of(Channel.EMAIL), Priority.NORMAL));
throw new IllegalStateException("missing variable expected");
} catch (IllegalArgumentException expected) {}
check(!svc.hasKey("k5"), "nothing recorded");
// 5. retries with backoff
fake(Channel.PUSH).fail(() -> new TransientError("timeout"), 2);
n = svc.submit(req("k6", "ben", Channel.PUSH));
check(svc.awaitIdle(t) && n.status() == Status.SENT, "retried");
check(sleeps.equals(List.of(Duration.ofMillis(500), Duration.ofMillis(1000))) && n.attempts.size() == 2, "backoff");
// 6. permanent error: fall back at once
fake(Channel.PUSH).fail(() -> new PermanentError("bad token"), 1);
n = svc.submit(req("k7", "ben", Channel.PUSH, Channel.SMS));
check(svc.awaitIdle(t) && n.channel == Channel.SMS && sleeps.size() == 2, "fallback");
// 7. exhausted
fake(Channel.PUSH).fail(() -> new TransientError("timeout"), 3);
n = svc.submit(req("k8", "ben", Channel.PUSH));
check(svc.awaitIdle(t) && n.status() == Status.FAILED && n.attempts.size() == 3, "failed");
// 8. quiet hours in the user's zone
clock.now = Instant.parse("2026-11-10T17:00:00Z"); // 22:30 in Kolkata
n = svc.submit(req("k9", "asha", Channel.EMAIL));
check(n.status() == Status.SCHEDULED && n.notBefore.equals(Instant.parse("2026-11-11T01:30:00Z")), "deferred");
Notification urgent = svc.submit(req("k10", "asha", List.of(Channel.EMAIL), "order_shipped", "orders", Priority.CRITICAL, Map.of()));
check(svc.releaseDue() == 0, "not yet");
clock.now = n.notBefore;
check(svc.releaseDue() == 1 && svc.awaitIdle(t), "released");
check(n.status() == Status.SENT && urgent.status() == Status.SENT, "both sent");
check(QuietHoursFilter.quietEnd(new QuietHours(LocalTime.of(23, 0), LocalTime.of(7, 0)),
Instant.parse("2026-03-08T04:30:00Z"), ZoneId.of("America/New_York"))
.equals(Instant.parse("2026-03-08T11:00:00Z")), "DST: 07:00 EDT is 11:00 UTC");
// 9. rate limit
NotificationService svc2 = build(new FakeClock(noon), 3);
List<Notification> got = new ArrayList<>();
for (int i = 0; i < 4; i++) got.add(svc2.submit(req("r" + i, "ben", Channel.EMAIL)));
check(svc2.awaitIdle(t), "idle");
check(got.stream().map(Notification::status).toList()
.equals(List.of(Status.SENT, Status.SENT, Status.SENT, Status.SUPPRESSED)), "rate limited");
svc2.shutdown();
// 10. a receipt that beats markSent is kept
NotificationService svc3 = build(new FakeClock(noon), 100);
senders.put(Channel.EMAIL, new FakeSender(key -> svc3.onReceipt(key.split(":")[0], true)));
n = svc3.submit(req("e1", "ben", Channel.EMAIL));
check(svc3.awaitIdle(t) && n.status() == Status.DELIVERED, "early receipt");
svc3.shutdown();
// 11. illegal transition
try { n.move(Status.SENDING, null); throw new IllegalStateException("terminal"); }
catch (IllegalTransition expected) {}
svc.shutdown();
System.out.println("notification service checks passed");
}
}
"""notify.py: an in-process notification service. Run: python notify.py"""
from __future__ import annotations
import itertools
import re
import threading
import time as _time
from collections import deque
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from datetime import datetime, time, timedelta, timezone
from enum import Enum
from typing import Callable, Protocol
from zoneinfo import ZoneInfo
# ---------- model ----------
class Channel(Enum):
EMAIL = "email"
SMS = "sms"
PUSH = "push"
IN_APP = "in_app"
class Priority(Enum):
NORMAL = "normal"
CRITICAL = "critical" # OTPs, security alerts: skip quiet hours and rate limits
class Status(Enum):
QUEUED = "QUEUED"
SCHEDULED = "SCHEDULED"
SENDING = "SENDING"
RETRYING = "RETRYING"
SENT = "SENT"
DELIVERED = "DELIVERED"
FAILED = "FAILED"
SUPPRESSED = "SUPPRESSED"
S = Status
ALLOWED: dict[Status, set[Status]] = {
S.QUEUED: {S.SENDING, S.SCHEDULED, S.SUPPRESSED},
S.SCHEDULED: {S.QUEUED},
S.SENDING: {S.SENT, S.RETRYING, S.FAILED},
S.RETRYING: {S.SENDING},
S.SENT: {S.DELIVERED, S.FAILED},
S.DELIVERED: set(), S.FAILED: set(), S.SUPPRESSED: set(),
}
class IllegalTransition(Exception): ...
class IdempotencyConflict(Exception): ...
class TransientError(Exception): ... # timeouts, 5xx, throttling: retry
class PermanentError(Exception): ... # bad address, unsubscribed at provider: try next channel
@dataclass(frozen=True)
class QuietHours:
start: time
end: time
def contains(self, t: time) -> bool:
if self.start <= self.end:
return self.start <= t < self.end
return t >= self.start or t < self.end # window wraps midnight
@dataclass
class User:
id: str
tz: str
addresses: dict[Channel, str]
opt_outs: set[str] = field(default_factory=set) # "marketing:sms" or "marketing:*"
quiet: QuietHours | None = None
@dataclass(frozen=True)
class Message:
subject: str
body: str
VAR = re.compile(r"\{(\w+)\}")
class Template:
def __init__(self, template_id: str, variants: dict[Channel, tuple[str, str]]) -> None:
self.id = template_id
self.variants = variants # channel -> (subject, body)
def render(self, channel: Channel, values: dict[str, str]) -> Message:
if channel not in self.variants:
raise ValueError(f"template {self.id} has no {channel.value} variant")
subject, body = self.variants[channel]
def sub(m: re.Match) -> str:
if m.group(1) not in values:
raise ValueError(f"template {self.id} needs variable '{m.group(1)}'")
return str(values[m.group(1)])
return Message(VAR.sub(sub, subject), VAR.sub(sub, body))
@dataclass(frozen=True)
class Request:
idempotency_key: str
user_id: str
template_id: str
values: dict[str, str]
category: str
channels: tuple[Channel, ...] # in order of preference; later ones are fallbacks
priority: Priority = Priority.NORMAL
class Notification:
_ids = itertools.count(1)
def __init__(self, request: Request, user: User) -> None:
self.id = f"n{next(Notification._ids)}"
self.request, self.user = request, user
self.channels: list[Channel] = list(request.channels)
self.status = Status.QUEUED
self.history = [Status.QUEUED]
self.attempts: list[str] = [] # "push#1: timeout"
self.channel: Channel | None = None
self.not_before: datetime | None = None
self.reason: str | None = None
self._early_receipt: bool | None = None
self._lock = threading.Lock()
def move(self, to: Status, reason: str | None = None) -> None:
with self._lock:
self._move(to, reason)
def _move(self, to: Status, reason: str | None) -> None:
if to not in ALLOWED[self.status]:
raise IllegalTransition(f"{self.id}: {self.status.value} -> {to.value}")
self.status = to
self.history.append(to)
if reason:
self.reason = reason
def mark_sent(self, channel: Channel) -> None:
with self._lock:
self.channel = channel
self._move(Status.SENT, None)
if self._early_receipt is not None: # the receipt beat us here
self._apply_receipt(self._early_receipt)
def receipt(self, delivered: bool) -> None:
with self._lock:
if self.status in (Status.SENDING, Status.RETRYING):
self._early_receipt = delivered
elif self.status == Status.SENT:
self._apply_receipt(delivered)
# DELIVERED or FAILED already: a duplicate receipt, ignore it
def _apply_receipt(self, delivered: bool) -> None:
self._move(Status.DELIVERED if delivered else Status.FAILED,
None if delivered else "bounced")
# ---------- channels (Strategy) ----------
class Sender(Protocol):
def send(self, address: str, message: Message, dedup_key: str) -> None: ...
class FakeSender:
"""Records what it sends. fail(kind, n) makes the next n sends raise."""
def __init__(self, on_send: Callable[[str], None] | None = None) -> None:
self.outbox: list[tuple[str, Message, str]] = []
self._script: deque[type[Exception]] = deque()
self._lock = threading.Lock()
self._on_send = on_send
def fail(self, kind: type[Exception], times: int = 1) -> "FakeSender":
self._script.extend([kind] * times)
return self
def send(self, address: str, message: Message, dedup_key: str) -> None:
with self._lock:
if self._script:
raise self._script.popleft()(f"scripted failure for {address}")
self.outbox.append((address, message, dedup_key))
if self._on_send:
self._on_send(dedup_key)
class InAppSender:
"""In-app needs no provider: the 'send' is a write to the user's inbox."""
def __init__(self) -> None:
self.inbox: dict[str, list[Message]] = {}
self._lock = threading.Lock()
def send(self, address: str, message: Message, dedup_key: str) -> None:
with self._lock:
self.inbox.setdefault(address, []).append(message)
# ---------- filters (Chain of Responsibility) ----------
@dataclass(frozen=True)
class Decision:
kind: str # "pass", "suppress", "defer"
reason: str = ""
until: datetime | None = None
PASS = Decision("pass")
class Filter(Protocol):
def check(self, n: Notification, now: datetime) -> Decision: ...
class PreferenceFilter:
def check(self, n: Notification, now: datetime) -> Decision:
cat, outs = n.request.category, n.user.opt_outs
n.channels = [c for c in n.channels
if f"{cat}:*" not in outs and f"{cat}:{c.value}" not in outs
and c in n.user.addresses]
return PASS if n.channels else Decision("suppress", "opted out or no address")
def quiet_end(q: QuietHours, now: datetime, tz: str) -> datetime:
"""The next instant at which local wall-clock time equals q.end, in the user's zone."""
local = now.astimezone(ZoneInfo(tz))
day = local.date() if local.time() < q.end else local.date() + timedelta(days=1)
return datetime.combine(day, q.end, ZoneInfo(tz)).astimezone(timezone.utc)
class QuietHoursFilter:
def check(self, n: Notification, now: datetime) -> Decision:
q = n.user.quiet
if q is None or n.request.priority is Priority.CRITICAL:
return PASS
if not q.contains(now.astimezone(ZoneInfo(n.user.tz)).time()):
return PASS
return Decision("defer", "quiet hours", quiet_end(q, now, n.user.tz))
class RateLimitFilter:
"""Sliding-window log per user. Runs last, so only sends that will happen use quota."""
def __init__(self, limit: int, window: timedelta) -> None:
self.limit, self.window = limit, window
self._log: dict[str, deque[datetime]] = {}
self._lock = threading.Lock()
def check(self, n: Notification, now: datetime) -> Decision:
if n.request.priority is Priority.CRITICAL:
return PASS
with self._lock:
log = self._log.setdefault(n.user.id, deque())
while log and log[0] <= now - self.window:
log.popleft()
if len(log) >= self.limit:
return Decision("suppress", "rate limited")
log.append(now)
return PASS
# ---------- the service ----------
class NotificationService:
def __init__(self, users: dict[str, User], templates: dict[str, Template],
senders: dict[Channel, Sender], filters: list[Filter],
clock: Callable[[], datetime], sleep: Callable[[float], None] = _time.sleep,
max_attempts: int = 3, backoff_s: float = 0.5, workers: int = 4) -> None:
self.users, self.templates, self.senders = users, templates, senders
self.filters, self.clock, self.sleep = filters, clock, sleep
self.max_attempts, self.backoff_s = max_attempts, backoff_s
self._by_key: dict[str, Notification] = {}
self._by_id: dict[str, Notification] = {}
self._scheduled: list[Notification] = []
self._pending = 0
self._lock = threading.Condition()
self._pool = ThreadPoolExecutor(max_workers=workers)
def submit(self, req: Request) -> Notification:
user = self.users.get(req.user_id)
template = self.templates.get(req.template_id)
if user is None or template is None:
raise ValueError("unknown user or template")
if not req.channels:
raise ValueError("at least one channel is required")
for ch in req.channels: # fail fast: a missing variable is the caller's bug
template.render(ch, req.values)
with self._lock: # check-and-insert must be one atomic step
existing = self._by_key.get(req.idempotency_key)
if existing is not None:
if existing.request != req:
raise IdempotencyConflict(f"key {req.idempotency_key} reused with a different request")
return existing
n = Notification(req, user)
self._by_key[req.idempotency_key] = n
self._by_id[n.id] = n
self._admit(n)
return n
def _admit(self, n: Notification) -> None:
now = self.clock()
for f in self.filters:
d = f.check(n, now)
if d.kind == "suppress":
n.move(Status.SUPPRESSED, d.reason)
return
if d.kind == "defer":
n.not_before = d.until
n.move(Status.SCHEDULED, d.reason)
with self._lock:
self._scheduled.append(n)
return
with self._lock:
self._pending += 1
self._pool.submit(self._deliver, n)
def release_due(self) -> int:
"""Called by a ticker. Moves due SCHEDULED notifications back through the filters."""
now = self.clock()
with self._lock:
due = [n for n in self._scheduled if n.not_before <= now]
self._scheduled = [n for n in self._scheduled if n.not_before > now]
for n in due:
n.move(Status.QUEUED)
self._admit(n) # opt-outs may have changed while it waited
return len(due)
def _deliver(self, n: Notification) -> None:
try:
n.move(Status.SENDING)
template = self.templates[n.request.template_id]
for ch in n.channels:
sender = self.senders.get(ch)
for attempt in range(1, self.max_attempts + 1):
try:
if sender is None:
raise PermanentError("no sender configured")
sender.send(n.user.addresses[ch], template.render(ch, n.request.values),
f"{n.id}:{ch.value}") # stable key: the provider can dedupe
n.mark_sent(ch)
return
except PermanentError as e:
n.attempts.append(f"{ch.value}#{attempt}: {e}")
break # this channel will never work: fall back
except Exception as e: # unknown errors are treated as transient
n.attempts.append(f"{ch.value}#{attempt}: {e}")
if attempt < self.max_attempts:
n.move(Status.RETRYING)
# Simplification: sleeps on the worker; a delay queue frees it (see task scheduler)
self.sleep(self.backoff_s * 2 ** (attempt - 1))
n.move(Status.SENDING)
n.move(Status.FAILED, "all channels failed")
finally:
with self._lock:
self._pending -= 1
self._lock.notify_all()
def on_receipt(self, notification_id: str, delivered: bool) -> None:
self._by_id[notification_id].receipt(delivered)
def get(self, notification_id: str) -> Notification:
return self._by_id[notification_id]
def wait_idle(self, timeout_s: float = 5) -> bool:
with self._lock:
return self._lock.wait_for(lambda: self._pending == 0, timeout_s)
def shutdown(self) -> None:
self._pool.shutdown(wait=True)
# ---------- demo and checks ----------
class FakeClock:
def __init__(self, at: datetime) -> None:
self.now = at
def __call__(self) -> datetime:
return self.now
def advance(self, **kw) -> None:
self.now += timedelta(**kw)
def build(clock: FakeClock, rate_limit: int = 100, **kw):
users = {
"asha": User("asha", "Asia/Kolkata",
{Channel.EMAIL: "asha@example.com", Channel.SMS: "+911", Channel.PUSH: "tok-a",
Channel.IN_APP: "asha"},
quiet=QuietHours(time(22, 0), time(7, 0))),
"ben": User("ben", "America/New_York",
{Channel.EMAIL: "ben@example.com", Channel.SMS: "+12", Channel.PUSH: "tok-b"},
opt_outs={"marketing:sms"}),
}
templates = {
"order_shipped": Template("order_shipped", {
Channel.EMAIL: ("Order {order} shipped", "Hi {name}, order {order} is on its way."),
Channel.SMS: ("", "Order {order} shipped."),
Channel.PUSH: ("Shipped", "Order {order} is on its way"),
Channel.IN_APP: ("Shipped", "Order {order} is on its way"),
}),
"sale": Template("sale", {
Channel.SMS: ("", "Sale: {pct}% off today"),
Channel.EMAIL: ("Sale", "Hi {name}, {pct}% off today"),
}),
}
senders = {Channel.EMAIL: FakeSender(), Channel.SMS: FakeSender(), Channel.PUSH: FakeSender(),
Channel.IN_APP: InAppSender()}
sleeps: list[float] = []
filters = [PreferenceFilter(), QuietHoursFilter(), RateLimitFilter(rate_limit, timedelta(hours=1))]
svc = NotificationService(users, templates, senders, filters, clock, sleep=sleeps.append, **kw)
return svc, senders, sleeps
def req(key: str, user: str = "ben", channels=(Channel.EMAIL,), template="order_shipped",
category="orders", priority=Priority.NORMAL, **values) -> Request:
vals = {"name": user.title(), "order": "A1", **values}
return Request(key, user, template, vals, category, tuple(channels), priority)
def demo() -> None:
noon_utc = datetime(2026, 11, 10, 12, 0, tzinfo=timezone.utc) # 17:30 in Kolkata
clock = FakeClock(noon_utc)
svc, senders, sleeps = build(clock)
# 1. happy path, then a delivery receipt
n = svc.submit(req("k1"))
assert svc.wait_idle()
assert n.status is Status.SENT and n.channel is Channel.EMAIL
assert senders[Channel.EMAIL].outbox[0][1].body == "Hi Ben, order A1 is on its way."
svc.on_receipt(n.id, delivered=True)
svc.on_receipt(n.id, delivered=True) # duplicate receipts are harmless
assert n.history == [S.QUEUED, S.SENDING, S.SENT, S.DELIVERED]
# 2. idempotency: 8 threads, one key, one send
before = len(senders[Channel.EMAIL].outbox)
with ThreadPoolExecutor(8) as ex:
results = list(ex.map(lambda _: svc.submit(req("k2")), range(8)))
assert svc.wait_idle()
assert len({r.id for r in results}) == 1
assert len(senders[Channel.EMAIL].outbox) == before + 1
try:
svc.submit(req("k2", order="B2"))
raise AssertionError("same key, different body must be rejected")
except IdempotencyConflict:
pass
# 3. opt-out narrows channels; opting out of everything suppresses
n = svc.submit(req("k3", template="sale", category="marketing", channels=(Channel.SMS, Channel.EMAIL), pct="20"))
assert svc.wait_idle() and n.channel is Channel.EMAIL
svc.users["ben"].opt_outs.add("marketing:*")
n = svc.submit(req("k4", template="sale", category="marketing", channels=(Channel.EMAIL,), pct="20"))
assert n.status is Status.SUPPRESSED
# 4. missing variable fails fast and creates nothing
try:
svc.submit(Request("k5", "ben", "order_shipped", {"name": "Ben"}, "orders", (Channel.EMAIL,)))
raise AssertionError("missing variable must raise")
except ValueError:
pass
assert "k5" not in svc._by_key
# 5. retries with exponential backoff, then success
senders[Channel.PUSH].fail(TransientError, 2)
n = svc.submit(req("k6", channels=(Channel.PUSH,)))
assert svc.wait_idle() and n.status is Status.SENT
assert sleeps == [0.5, 1.0] and len(n.attempts) == 2
# 6. fallback: a permanent push error falls through to SMS at once
senders[Channel.PUSH].fail(PermanentError, 1)
n = svc.submit(req("k7", channels=(Channel.PUSH, Channel.SMS)))
assert svc.wait_idle() and n.channel is Channel.SMS and sleeps == [0.5, 1.0]
# 7. every channel exhausted
senders[Channel.PUSH].fail(TransientError, 3)
n = svc.submit(req("k8", channels=(Channel.PUSH,)))
assert svc.wait_idle() and n.status is Status.FAILED and len(n.attempts) == 3
# 8. quiet hours are local: 17:00 UTC is 22:30 in Kolkata
clock.now = datetime(2026, 11, 10, 17, 0, tzinfo=timezone.utc)
n = svc.submit(req("k9", user="asha"))
assert n.status is Status.SCHEDULED
assert n.not_before == datetime(2026, 11, 11, 1, 30, tzinfo=timezone.utc) # 07:00 IST
urgent = svc.submit(req("k10", user="asha", priority=Priority.CRITICAL))
assert svc.release_due() == 0
clock.now = n.not_before
assert svc.release_due() == 1 and svc.wait_idle()
assert n.status is Status.SENT and urgent.status is Status.SENT
assert n.history == [S.QUEUED, S.SCHEDULED, S.QUEUED, S.SENDING, S.SENT]
# 9. rate limit: 3 per hour per user
svc2, _, _ = build(FakeClock(noon_utc), rate_limit=3)
got = [svc2.submit(req(f"r{i}")) for i in range(4)]
assert svc2.wait_idle()
assert [g.status for g in got] == [S.SENT, S.SENT, S.SENT, S.SUPPRESSED]
svc2.shutdown()
# 10. a receipt that arrives before SENT is recorded is kept, not lost
holder: dict[str, NotificationService] = {}
early = FakeSender(on_send=lambda key: holder["svc"].on_receipt(key.split(":")[0], True))
svc3, _, _ = build(FakeClock(noon_utc))
svc3.senders[Channel.EMAIL] = early
holder["svc"] = svc3
n = svc3.submit(req("e1"))
assert svc3.wait_idle() and n.status is Status.DELIVERED
svc3.shutdown()
# 11. illegal transitions are refused
try:
n.move(Status.SENDING)
raise AssertionError("DELIVERED is terminal")
except IllegalTransition:
pass
svc.shutdown()
print("notification service checks passed")
if __name__ == "__main__":
demo()
// notify.ts -> npx tsx notify.ts (typechecks with tsc --strict --target es2022 --lib es2022,dom)
import assert from "node:assert/strict";
export type Channel = "email" | "sms" | "push" | "in_app";
export type Priority = "normal" | "critical";
export type Status =
| "QUEUED" | "SCHEDULED" | "SENDING" | "RETRYING" | "SENT" | "DELIVERED" | "FAILED" | "SUPPRESSED";
const ALLOWED: Record<Status, Status[]> = {
QUEUED: ["SENDING", "SCHEDULED", "SUPPRESSED"],
SCHEDULED: ["QUEUED"],
SENDING: ["SENT", "RETRYING", "FAILED"],
RETRYING: ["SENDING"],
SENT: ["DELIVERED", "FAILED"],
DELIVERED: [], FAILED: [], SUPPRESSED: [],
};
export class IllegalTransition extends Error {}
export class IdempotencyConflict extends Error {}
export class TransientError extends Error {}
export class PermanentError extends Error {}
/** Minutes since local midnight, e.g. 22:00 is 1320. */
export interface QuietHours { start: number; end: number }
export function inQuiet(q: QuietHours, m: number): boolean {
return q.start <= q.end ? q.start <= m && m < q.end : m >= q.start || m < q.end;
}
export function localMinutes(at: Date, timeZone: string): number {
const parts = new Intl.DateTimeFormat("en-US", { timeZone, hour: "2-digit", minute: "2-digit", hourCycle: "h23" })
.formatToParts(at);
const get = (t: string) => Number(parts.find((p) => p.type === t)!.value);
return get("hour") * 60 + get("minute");
}
/** The next instant whose local wall-clock time is q.end. One correction step absorbs a DST jump. */
export function quietEnd(q: QuietHours, now: Date, timeZone: string): Date {
const minute = 60_000;
const base = Math.floor(now.getTime() / minute) * minute;
const ahead = (q.end - localMinutes(now, timeZone) + 1440) % 1440 || 1440;
let candidate = base + ahead * minute;
let drift = q.end - localMinutes(new Date(candidate), timeZone);
if (drift > 720) drift -= 1440;
if (drift < -720) drift += 1440;
candidate += drift * minute;
return new Date(candidate);
}
export interface User {
id: string; tz: string; addresses: Partial<Record<Channel, string>>;
optOuts: Set<string>; // "marketing:sms" or "marketing:*"
quiet?: QuietHours;
}
export interface Message { subject: string; body: string }
export class Template {
constructor(readonly id: string, private readonly variants: Partial<Record<Channel, [string, string]>>) {}
render(ch: Channel, values: Record<string, string>): Message {
const v = this.variants[ch];
if (!v) throw new Error(`template ${this.id} has no ${ch} variant`);
const fill = (text: string) =>
text.replace(/\{(\w+)\}/g, (_, name: string) => {
if (!(name in values)) throw new Error(`template ${this.id} needs variable '${name}'`);
return values[name];
});
return { subject: fill(v[0]), body: fill(v[1]) };
}
}
export interface Request {
idempotencyKey: string; userId: string; templateId: string; values: Record<string, string>;
category: string; channels: Channel[]; priority?: Priority;
}
const sameRequest = (a: Request, b: Request) => JSON.stringify(a) === JSON.stringify(b);
let nextId = 1;
export class Notification {
readonly id = `n${nextId++}`;
channels: Channel[];
status: Status = "QUEUED";
readonly history: Status[] = ["QUEUED"];
readonly attempts: string[] = [];
channel?: Channel;
notBefore?: Date;
reason?: string;
private earlyReceipt?: boolean;
constructor(readonly request: Request, readonly user: User) {
this.channels = [...request.channels];
}
move(to: Status, reason?: string): void {
if (!ALLOWED[this.status].includes(to)) throw new IllegalTransition(`${this.id}: ${this.status} -> ${to}`);
this.status = to;
this.history.push(to);
if (reason) this.reason = reason;
}
markSent(ch: Channel): void {
this.channel = ch;
this.move("SENT");
if (this.earlyReceipt !== undefined) this.applyReceipt(this.earlyReceipt);
}
receipt(delivered: boolean): void {
if (this.status === "SENDING" || this.status === "RETRYING") this.earlyReceipt = delivered;
else if (this.status === "SENT") this.applyReceipt(delivered);
}
private applyReceipt(delivered: boolean): void {
this.move(delivered ? "DELIVERED" : "FAILED", delivered ? undefined : "bounced");
}
}
// ---------- channels (Strategy) ----------
export interface Sender { send(address: string, message: Message, dedupKey: string): Promise<void> }
export class FakeSender implements Sender {
readonly outbox: Message[] = [];
private readonly script: (() => Error)[] = [];
constructor(private readonly onSend: (key: string) => void = () => {}) {}
fail(make: () => Error, times = 1): this {
for (let i = 0; i < times; i++) this.script.push(make);
return this;
}
async send(_address: string, message: Message, dedupKey: string): Promise<void> {
await Promise.resolve(); // a real provider call yields here
const next = this.script.shift();
if (next) throw next();
this.outbox.push(message);
this.onSend(dedupKey);
}
}
export class InAppSender implements Sender {
readonly inbox = new Map<string, Message[]>();
async send(address: string, message: Message): Promise<void> {
const list = this.inbox.get(address) ?? [];
list.push(message);
this.inbox.set(address, list);
}
}
// ---------- filters (Chain of Responsibility) ----------
export type Decision =
| { kind: "pass" } | { kind: "suppress"; reason: string } | { kind: "defer"; reason: string; until: Date };
const PASS: Decision = { kind: "pass" };
export interface Filter { check(n: Notification, now: Date): Decision }
export class PreferenceFilter implements Filter {
check(n: Notification): Decision {
const cat = n.request.category, outs = n.user.optOuts;
n.channels = n.channels.filter((c) => !outs.has(`${cat}:*`) && !outs.has(`${cat}:${c}`) && n.user.addresses[c]);
return n.channels.length ? PASS : { kind: "suppress", reason: "opted out or no address" };
}
}
export class QuietHoursFilter implements Filter {
check(n: Notification, now: Date): Decision {
const q = n.user.quiet;
if (!q || n.request.priority === "critical") return PASS;
if (!inQuiet(q, localMinutes(now, n.user.tz))) return PASS;
return { kind: "defer", reason: "quiet hours", until: quietEnd(q, now, n.user.tz) };
}
}
export class RateLimitFilter implements Filter {
private readonly log = new Map<string, number[]>();
constructor(private readonly limit: number, private readonly windowMs: number) {}
check(n: Notification, now: Date): Decision {
if (n.request.priority === "critical") return PASS;
const t = now.getTime();
const times = (this.log.get(n.user.id) ?? []).filter((x) => x > t - this.windowMs);
if (times.length >= this.limit) {
this.log.set(n.user.id, times);
return { kind: "suppress", reason: "rate limited" };
}
times.push(t);
this.log.set(n.user.id, times);
return PASS;
}
}
// ---------- the service ----------
export interface Options {
users: Map<string, User>; templates: Map<string, Template>; senders: Map<Channel, Sender>;
filters: Filter[]; clock: () => Date; sleep?: (ms: number) => Promise<void>;
maxAttempts?: number; backoffMs?: number; workers?: number;
}
export class NotificationService {
private readonly byKey = new Map<string, Notification>();
private readonly byId = new Map<string, Notification>();
private scheduled: Notification[] = [];
private readonly queue: Notification[] = [];
private running = 0;
private idleWaiters: (() => void)[] = [];
readonly users: Map<string, User>;
readonly senders: Map<Channel, Sender>;
private readonly sleep: (ms: number) => Promise<void>;
private readonly maxAttempts: number;
private readonly backoffMs: number;
private readonly workers: number;
constructor(private readonly o: Options) {
this.users = o.users;
this.senders = o.senders;
this.sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
this.maxAttempts = o.maxAttempts ?? 3;
this.backoffMs = o.backoffMs ?? 500;
this.workers = o.workers ?? 4;
}
submit(req: Request): Notification {
const user = this.o.users.get(req.userId);
const template = this.o.templates.get(req.templateId);
if (!user || !template) throw new Error("unknown user or template");
if (req.channels.length === 0) throw new Error("at least one channel is required");
for (const ch of req.channels) template.render(ch, req.values);
// No await between the lookup and the insert, so this is atomic on the event loop.
const existing = this.byKey.get(req.idempotencyKey);
if (existing) {
if (!sameRequest(existing.request, req))
throw new IdempotencyConflict(`key ${req.idempotencyKey} reused with a different request`);
return existing;
}
const n = new Notification(req, user);
this.byKey.set(req.idempotencyKey, n);
this.byId.set(n.id, n);
this.admit(n);
return n;
}
has(key: string): boolean { return this.byKey.has(key); }
get(id: string): Notification | undefined { return this.byId.get(id); }
private admit(n: Notification): void {
const now = this.o.clock();
for (const f of this.o.filters) {
const d = f.check(n, now);
if (d.kind === "suppress") { n.move("SUPPRESSED", d.reason); return; }
if (d.kind === "defer") {
n.notBefore = d.until;
n.move("SCHEDULED", d.reason);
this.scheduled.push(n);
return;
}
}
this.queue.push(n);
this.pump();
}
/** Worker pool: at most `workers` deliveries in flight. */
private pump(): void {
while (this.running < this.workers && this.queue.length) {
const n = this.queue.shift()!;
this.running++;
void this.deliver(n).finally(() => {
this.running--;
this.pump();
if (this.running === 0 && this.queue.length === 0) {
const waiters = this.idleWaiters;
this.idleWaiters = [];
waiters.forEach((w) => w());
}
});
}
}
releaseDue(): number {
const now = this.o.clock().getTime();
const due = this.scheduled.filter((n) => n.notBefore!.getTime() <= now);
this.scheduled = this.scheduled.filter((n) => n.notBefore!.getTime() > now);
for (const n of due) { n.move("QUEUED"); this.admit(n); }
return due.length;
}
private async deliver(n: Notification): Promise<void> {
n.move("SENDING");
const template = this.o.templates.get(n.request.templateId)!;
for (const ch of n.channels) {
const sender = this.o.senders.get(ch);
for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
try {
if (!sender) throw new PermanentError("no sender configured");
await sender.send(n.user.addresses[ch]!, template.render(ch, n.request.values), `${n.id}:${ch}`);
n.markSent(ch);
return;
} catch (e) {
n.attempts.push(`${ch}#${attempt}: ${(e as Error).message}`);
if (e instanceof PermanentError) break;
if (attempt < this.maxAttempts) {
n.move("RETRYING");
await this.sleep(this.backoffMs * 2 ** (attempt - 1)); // frees the event loop, not a thread
n.move("SENDING");
}
}
}
}
n.move("FAILED", "all channels failed");
}
onReceipt(id: string, delivered: boolean): void { this.byId.get(id)!.receipt(delivered); }
waitIdle(): Promise<void> {
if (this.running === 0 && this.queue.length === 0) return Promise.resolve();
return new Promise((r) => this.idleWaiters.push(r));
}
}
// ---------- demo and checks ----------
export function build(clock: { now: Date }, rateLimit = 100) {
const users = new Map<string, User>([
["asha", { id: "asha", tz: "Asia/Kolkata", optOuts: new Set(), quiet: { start: 22 * 60, end: 7 * 60 },
addresses: { email: "asha@example.com", sms: "+911", push: "tok-a", in_app: "asha" } }],
["ben", { id: "ben", tz: "America/New_York", optOuts: new Set(["marketing:sms"]),
addresses: { email: "ben@example.com", sms: "+12", push: "tok-b" } }],
]);
const templates = new Map([
["order_shipped", new Template("order_shipped", {
email: ["Order {order} shipped", "Hi {name}, order {order} is on its way."],
sms: ["", "Order {order} shipped."],
push: ["Shipped", "Order {order} is on its way"],
in_app: ["Shipped", "Order {order} is on its way"],
})],
["sale", new Template("sale", { sms: ["", "Sale: {pct}% off today"], email: ["Sale", "Hi {name}, {pct}% off today"] })],
]);
const fakes = { email: new FakeSender(), sms: new FakeSender(), push: new FakeSender() };
const senders = new Map<Channel, Sender>([...Object.entries(fakes), ["in_app", new InAppSender()]] as [Channel, Sender][]);
const sleeps: number[] = [];
const svc = new NotificationService({
users, templates, senders, clock: () => clock.now,
filters: [new PreferenceFilter(), new QuietHoursFilter(), new RateLimitFilter(rateLimit, 3_600_000)],
sleep: async (ms) => { sleeps.push(ms); },
});
return { svc, fakes, sleeps };
}
export function req(key: string, over: Partial<Request> = {}, extra: Record<string, string> = {}): Request {
const userId = over.userId ?? "ben";
return {
idempotencyKey: key, userId, templateId: "order_shipped", category: "orders", channels: ["email"],
priority: "normal", ...over,
values: { name: userId[0].toUpperCase() + userId.slice(1), order: "A1", ...extra },
};
}
async function demo(): Promise<void> {
const noon = new Date("2026-11-10T12:00:00Z");
const clock = { now: noon };
const { svc, fakes, sleeps } = build(clock);
let n = svc.submit(req("k1"));
await svc.waitIdle();
assert.equal(n.status, "SENT");
assert.equal(fakes.email.outbox[0].body, "Hi Ben, order A1 is on its way.");
svc.onReceipt(n.id, true);
svc.onReceipt(n.id, true);
assert.deepEqual(n.history, ["QUEUED", "SENDING", "SENT", "DELIVERED"]);
const before = fakes.email.outbox.length;
const same = await Promise.all(Array.from({ length: 8 }, async () => svc.submit(req("k2"))));
await svc.waitIdle();
assert.equal(new Set(same.map((x) => x.id)).size, 1);
assert.equal(fakes.email.outbox.length, before + 1);
assert.throws(() => svc.submit(req("k2", {}, { order: "B2" })), IdempotencyConflict);
n = svc.submit(req("k3", { templateId: "sale", category: "marketing", channels: ["sms", "email"] }, { pct: "20" }));
await svc.waitIdle();
assert.equal(n.channel, "email");
svc.users.get("ben")!.optOuts.add("marketing:*");
n = svc.submit(req("k4", { templateId: "sale", category: "marketing" }, { pct: "20" }));
assert.equal(n.status, "SUPPRESSED");
assert.throws(() => svc.submit({ ...req("k5"), values: { name: "Ben" } }), /needs variable 'order'/);
assert.equal(svc.has("k5"), false);
fakes.push.fail(() => new TransientError("timeout"), 2);
n = svc.submit(req("k6", { channels: ["push"] }));
await svc.waitIdle();
assert.equal(n.status, "SENT");
assert.deepEqual(sleeps, [500, 1000]);
fakes.push.fail(() => new PermanentError("bad token"));
n = svc.submit(req("k7", { channels: ["push", "sms"] }));
await svc.waitIdle();
assert.equal(n.channel, "sms");
assert.equal(sleeps.length, 2);
fakes.push.fail(() => new TransientError("timeout"), 3);
n = svc.submit(req("k8", { channels: ["push"] }));
await svc.waitIdle();
assert.equal(n.status, "FAILED");
assert.equal(n.attempts.length, 3);
clock.now = new Date("2026-11-10T17:00:00Z"); // 22:30 in Kolkata
n = svc.submit(req("k9", { userId: "asha" }));
assert.equal(n.status, "SCHEDULED");
assert.equal(n.notBefore!.toISOString(), "2026-11-11T01:30:00.000Z");
const urgent = svc.submit(req("k10", { userId: "asha", priority: "critical" }));
assert.equal(svc.releaseDue(), 0);
clock.now = n.notBefore!;
assert.equal(svc.releaseDue(), 1);
await svc.waitIdle();
assert.equal(n.status, "SENT");
assert.equal(urgent.status, "SENT");
assert.equal(quietEnd({ start: 23 * 60, end: 7 * 60 }, new Date("2026-03-08T04:30:00Z"), "America/New_York")
.toISOString(), "2026-03-08T11:00:00.000Z"); // DST starts that night
const b2 = build({ now: noon }, 3);
const got = [0, 1, 2, 3].map((i) => b2.svc.submit(req(`r${i}`)));
await b2.svc.waitIdle();
assert.deepEqual(got.map((g) => g.status), ["SENT", "SENT", "SENT", "SUPPRESSED"]);
const b3 = build({ now: noon });
b3.svc.senders.set("email", new FakeSender((key) => b3.svc.onReceipt(key.split(":")[0], true)));
n = b3.svc.submit(req("e1"));
await b3.svc.waitIdle();
assert.equal(n.status, "DELIVERED");
assert.throws(() => n.move("SENDING"), IllegalTransition);
console.log("notification service checks passed");
}
if (process.argv[1]?.endsWith("notify.ts")) await demo();
Walking through the important decisions
Validate, then store, then decide. submit does every check that can fail on bad input first: user, template, channel variants, variables. Only then does it take the lock and insert. If it inserted first and validation failed afterwards, the key would be burned: a corrected retry with the same key would get back a broken record. Error Handling in Object Design calls this "fail fast at the boundary".
Rendering happens twice, on purpose. submit renders every requested channel once to validate, and throws the result away. deliver renders again for the channel it actually uses. The cost is microseconds, and it keeps the stored request as the single source of truth. Caching rendered messages on the record would be a second copy that could drift if a template changed between deferral and release. Whether a template change should affect a deferred message is a fair follow-up. This design says yes.
The preference filter narrows the channel list on the record. That's the one filter with a side effect. The alternative is returning the narrowed list inside the Decision, which is purer but makes every filter's return type carry a channel list it doesn't care about. On release, admit runs the preference filter again against the already narrowed list, which is correct: channels only ever get removed.
Quiet-hours end time is computed in the user's zone, then converted to UTC. Take today's date in the user's zone. If the local time is already past the end of the window, use tomorrow. Combine that date with the end time in that zone, and let the time-zone library pick the offset. Doing it as "now plus the difference in minutes" is wrong across a daylight-saving change, and the demo includes the case that proves it. On 8 March 2026 New York moves its clocks forward at 02:00, so 07:00 local is 11:00 UTC that morning, not 12:00. The TypeScript version has no zone-aware date type in the standard library, so it computes the minute difference and then applies one correction step after checking the candidate's local time with Intl.DateTimeFormat. That absorbs a one-hour jump.
Wrapping windows. 22:00 to 07:00 wraps midnight. contains handles that with two cases: if start <= end the window is a plain range, otherwise it's "after start or before end". Forgetting the second case is one of the most common bugs in this question.
Unknown exceptions are transient. A KeyError from a provider client, or a null pointer inside an SDK, is retried. The reasoning: if it's really permanent, retrying costs a few hundred milliseconds. If it's transient and we gave up, we lost a message. Only errors the sender explicitly classifies as permanent skip retries.
The backoff sleeps on the worker. It is a deliberate shortcut, marked with a comment in the code. While a worker sleeps, it isn't sending anything else, so a provider outage with many retrying notifications can starve the pool. The production fix is to put the retry into a delay queue with a notBefore time, the same mechanism quiet hours already use, and free the worker. The task scheduler case study builds that delay queue. In TypeScript the problem doesn't arise, because await sleep() frees the event loop for other deliveries.
7. Concurrency
What's shared
| State | Written by | Protected by |
|---|---|---|
byKey, byId | submit | The service lock, held only for check-and-insert |
scheduled list | admit (defer), releaseDue | The service lock |
pending counter | admit, deliver's finally | The service lock, plus a condition for awaitIdle |
| A notification's status, history, early receipt | Workers, receipt webhooks, releaseDue | The notification's own lock |
| Rate-limit log | RateLimitFilter.check from any submitting thread | The filter's own lock |
| A user's opt-outs | Preference updates from elsewhere | A concurrent set in Java. In Python, set membership checks are safe under the GIL, but a real system would copy on write. |
Request, Message, Template | Nobody after creation | Immutability |
Lock granularity
There are three kinds of lock, and none is ever held while calling a provider.
- The service lock guards the maps and the counter. Critical sections are a few dictionary operations. It's never held during filtering or sending.
- One lock per notification guards its status. Two threads touch the same notification only in two cases: the worker and a webhook (the early-receipt case), or a duplicate webhook. Per-record locks mean thousands of notifications can change state in parallel.
- One lock in the rate limiter guards all users' windows. That's a hotspot under heavy load, and the fix is a lock per user, or striping by user id. It's fine for an interview. Say so if asked.
Lock ordering. Notification.markSent holds the record lock and calls move, which is the same lock (re-entrant in Java via synchronized, and Python's version calls the unlocked _move internally). No code path holds the service lock and then takes a record lock, or the other way round, so there's no ordering to get wrong. admit releases the service lock before calling filters. That rule, never call out while holding a lock, is the same one the pub-sub broker depends on.
Races designed out
| Race | What would go wrong | Prevention |
|---|---|---|
| Two threads submit the same key | Two sends | Check-and-insert under one lock |
A webhook receipt arrives before markSent | Illegal transition or a lost receipt | The record buffers one early receipt and applies it in markSent |
| Duplicate webhook | DELIVERED → DELIVERED error | receipt ignores receipts in terminal states |
releaseDue runs on two ticker threads | The same notification sent twice | releaseDue removes due items from the list under the lock before releasing any of them, so each is released by exactly one caller |
| Two threads check the rate limit for one user | Both see 2 of 3, both send, the user gets 4 | The window check and the append are one critical section |
awaitIdle returns before a deferred send finishes | Flaky tests | pending counts only work handed to the pool. Scheduled items aren't pending until released. |
The idempotency map grows forever
A map of every key ever seen is a memory leak with a long fuse. Real systems expire keys after a window, typically 24 hours to a few days, chosen to cover the longest a caller might keep retrying. In memory that's a map plus a time-ordered queue for eviction. In a database it's a unique index on the key and a TTL job. The trade-off to name: after expiry, a very late retry will send again. That's acceptable if the window is longer than any realistic retry.
Thread count
The pool size is the number of concurrent provider calls. Provider calls are I/O-bound, so the pool can be much larger than the core count. A rough starting point is "target throughput × provider latency": 200 sends per second at 100 ms each needs about 20 threads. Java 21+ virtual threads change the arithmetic, because a blocked virtual thread costs almost nothing, so Executors.newVirtualThreadPerTaskExecutor() plus a semaphore for the provider's own rate limit is a reasonable modern answer. Thread-Safe Class Design covers the general choices.
8. Extensibility: "the interviewer adds X"
Extension A: a circuit breaker per channel
"The SMS provider has been down for ten minutes. Every notification spends three retries on it before falling back to email. Stop that."
Retries handle a blip. They make an outage worse, because every notification pays the full retry cost and the provider gets hammered while it's trying to recover. A circuit breaker notices repeated failures and fails fast for a cooldown period. Because a sender is a one-method interface, the breaker is a Decorator: it implements Sender, holds the real sender, and the service doesn't change at all.
The key design choice is what error the breaker raises when open. It raises PermanentError, because for this notification, retrying is pointless while the circuit is open. That makes the existing delivery loop skip straight to the fallback channel with no extra code.
"""Extension A: a circuit breaker per channel, as a Decorator around a Sender."""
import threading
from datetime import datetime, timedelta, timezone
from notify import (Channel, FakeClock, PermanentError, Status, TransientError, build, req)
class CircuitBreakerSender:
"""After `threshold` consecutive failures, fail fast for `cooldown`, then let one probe through."""
def __init__(self, inner, clock, threshold: int = 3, cooldown: timedelta = timedelta(seconds=30)) -> None:
self.inner, self.clock = inner, clock
self.threshold, self.cooldown = threshold, cooldown
self.failures = 0
self.open_until: datetime | None = None
self._lock = threading.Lock()
def send(self, address, message, dedup_key) -> None:
with self._lock:
if self.open_until and self.clock() < self.open_until:
# Permanent for *this* notification: skip straight to the fallback channel.
raise PermanentError("circuit open")
try:
self.inner.send(address, message, dedup_key)
except Exception:
with self._lock:
self.failures += 1
if self.failures >= self.threshold:
self.open_until = self.clock() + self.cooldown
raise
with self._lock:
self.failures, self.open_until = 0, None
if __name__ == "__main__":
clock = FakeClock(datetime(2026, 11, 10, 12, 0, tzinfo=timezone.utc))
svc, senders, sleeps = build(clock, max_attempts=1)
push = senders[Channel.PUSH].fail(TransientError, 3) # the push provider is down
svc.senders[Channel.PUSH] = CircuitBreakerSender(push, clock, threshold=3)
for i in range(3): # three failures open the circuit; each falls back to SMS
n = svc.submit(req(f"cb{i}", channels=(Channel.PUSH, Channel.SMS)))
assert svc.wait_idle() and n.channel is Channel.SMS
n = svc.submit(req("cb3", channels=(Channel.PUSH, Channel.SMS)))
assert svc.wait_idle() and n.channel is Channel.SMS
assert n.attempts == ["push#1: circuit open"] # failed fast, provider not called
clock.advance(seconds=31) # cooldown over: a probe goes through and closes the circuit
n = svc.submit(req("cb4", channels=(Channel.PUSH, Channel.SMS)))
assert svc.wait_idle() and n.channel is Channel.PUSH and n.status is Status.SENT
svc.shutdown()
print("circuit breaker checks passed")
What changed: one new class, and one line to wrap the sender when building the service. What to say: this breaker is per channel. With two SMS providers you'd put a breaker on each, behind a sender that picks the healthy one, which is another strategy.
Extension B: digests instead of a flood
"When a post goes viral, the author gets 400 'X liked your post' pushes in an hour. Send one 'Chen and 399 others liked your post' every 15 minutes instead."
This is the most common extension, and it's tempting to do it inside the service with a special filter that holds notifications back. Don't. A digest isn't a rule about one notification. It's a different producer that turns many events into one request. So it sits in front of the service: a DigestCollector buffers events per (user, time window) and flush() submits one request per closed window.
The idempotency key is derived from the window: digest:<user>:<window number>. If the flush job crashes after submitting and runs again, it submits the same key and nothing is sent twice. That's the general trick: derive keys from the identity of the work, never from a random UUID generated at send time.
"""Extension B: batch noisy events into one digest per user per window."""
import threading
from collections import defaultdict
from datetime import datetime, timedelta, timezone
from notify import Channel, FakeClock, Request, Template, build
class DigestCollector:
"""Sits in front of the service. Collects events, then flush() submits one notification each."""
def __init__(self, svc, clock, window: timedelta) -> None:
self.svc, self.clock, self.window = svc, clock, window
self._events: dict[tuple[str, int], list[str]] = defaultdict(list)
self._lock = threading.Lock()
def _bucket(self, at: datetime) -> int:
return int(at.timestamp() // self.window.total_seconds())
def add(self, user_id: str, actor: str) -> None:
with self._lock:
self._events[(user_id, self._bucket(self.clock()))].append(actor)
def flush(self) -> list:
current = self._bucket(self.clock())
with self._lock:
ready = {k: v for k, v in self._events.items() if k[1] < current} # closed windows only
for k in ready:
del self._events[k]
sent = []
for (user_id, bucket), actors in sorted(ready.items()):
others = len(actors) - 1
text = actors[0] if others == 0 else f"{actors[0]} and {others} others"
# The key is derived from the window, so a flush retried after a crash sends nothing twice.
sent.append(self.svc.submit(Request(f"digest:{user_id}:{bucket}", user_id, "likes",
{"who": text}, "social", (Channel.PUSH,))))
return sent
if __name__ == "__main__":
clock = FakeClock(datetime(2026, 11, 10, 12, 0, tzinfo=timezone.utc))
svc, senders, _ = build(clock)
svc.templates["likes"] = Template("likes", {Channel.PUSH: ("New likes", "{who} liked your post")})
digest = DigestCollector(svc, clock, timedelta(minutes=15))
for who in ["Chen", "Dev", "Eli", "Fay"]:
digest.add("ben", who)
assert digest.flush() == [] # the window is still open
clock.advance(minutes=15)
[n] = digest.flush()
assert svc.wait_idle()
assert senders[Channel.PUSH].outbox[-1][1].body == "Chen and 3 others liked your post"
# A replayed flush with the same window resubmits the same key and sends nothing new.
again = svc.submit(n.request)
assert again is n and len(senders[Channel.PUSH].outbox) == 1
svc.shutdown()
print("digest checks passed")
What changed: nothing in the service. One new class and one template. What to say: the window here is fixed (aligned to clock time), which is simple and predictable. A sliding "15 minutes after the first like" window feels more responsive but needs a scheduled flush per user, which is the task-scheduler problem again.
Extension C: escalate when a message bounces
"If the email bounces, send an SMS."
Synchronous fallback already happens when a provider rejects the send. A bounce is different: the provider accepted the message, we moved it to SENT, and minutes later a receipt says it failed. The state machine already has SENT → FAILED. The extension listens for that and submits a follow-up request for the remaining channels, again with a derived key (k:after-email) so a provider that repeats its bounce webhook can't trigger two SMS messages.
"""Extension C: escalate to the next channel when the provider reports a bounce."""
from dataclasses import replace
from datetime import datetime, timezone
from notify import Channel, FakeClock, NotificationService, Status, build, req
class EscalatingService(NotificationService):
def on_receipt(self, notification_id: str, delivered: bool) -> None:
super().on_receipt(notification_id, delivered)
n = self.get(notification_id)
if n.status is not Status.FAILED or n.channel is None:
return
remaining = n.channels[n.channels.index(n.channel) + 1:]
if remaining: # derived key: a duplicate bounce receipt can't escalate twice
self.submit(replace(n.request, idempotency_key=f"{n.request.idempotency_key}:after-{n.channel.value}",
channels=tuple(remaining)))
if __name__ == "__main__":
clock = FakeClock(datetime(2026, 11, 10, 12, 0, tzinfo=timezone.utc))
base, senders, _ = build(clock)
svc = EscalatingService(base.users, base.templates, base.senders, base.filters, clock, sleep=lambda s: None)
n = svc.submit(req("x1", channels=(Channel.EMAIL, Channel.SMS)))
assert svc.wait_idle() and n.channel is Channel.EMAIL
svc.on_receipt(n.id, delivered=False) # hard bounce from the email provider
svc.on_receipt(n.id, delivered=False) # the provider repeats itself
assert svc.wait_idle()
assert n.status is Status.FAILED and n.reason == "bounced"
assert len(senders[Channel.SMS].outbox) == 1 # exactly one escalation
base.shutdown()
svc.shutdown()
print("escalation checks passed")
What changed: a subclass that overrides one method. An Observer on status changes would be the cleaner shape once there are several listeners (analytics, escalation, an audit log), and that's the moment to introduce one. Note the follow-up is a new notification with its own record and its own history, not the old one resurrected. Terminal states stay terminal.
Other extensions to be ready for, with where the change goes:
| Extension | Change |
|---|---|
| A new channel (WhatsApp, Slack) | A new Channel value, a new Sender, a template variant per template that should use it |
| Scheduled send ("at 9 a.m. the user's time") | A sendAt field on the request and a filter that defers until then. The SCHEDULED machinery already exists. |
| Priority lanes | Two pools, or a priority queue in front of one pool, so OTPs never wait behind a marketing blast |
| Localised templates | Key templates by (id, locale) and add a locale to the user. Rendering is unchanged. |
| Per-category frequency caps | Another Filter. Insert it before the global rate limiter. |
| Persistence | Repositories behind the maps, a unique index on the idempotency key, and a recovery job that re-queues records stuck in SENDING after a crash |
9. Testing approach
The injected seams decide how easy testing is. Everything that's slow, random or external is passed in:
| Seam | Production | Test |
|---|---|---|
| Clock | Instant.now() | FakeClock you set and advance |
| Sleep | Thread.sleep | A function that records the duration and returns at once |
| Senders | Provider adapters | FakeSender with an outbox and a failure script |
| Pool size | Tuned | Small, plus awaitIdle to wait for completion |
With those seams, no test sleeps for a fixed time to "let the workers finish". Tests call wait_idle(), which blocks on a condition until the pending count reaches zero. That makes them fast when they pass and deterministic when the machine is busy.
What to cover:
- Templates. Every variable is substituted. A missing one is rejected before anything is stored. A channel without a variant is rejected.
- Idempotency. 64 concurrent submits of one key produce one record and one send. Reusing a key with a different payload raises. A retried request for a notification that already failed returns the failed record and doesn't send again. The provider receives a stable dedup key.
- Preferences. A channel-level opt-out falls through to the next channel. A category-wide opt-out suppresses. An opt-out in one category doesn't affect another. A channel with no address is skipped.
- Quiet hours. A wrapping window contains 23:59 and 00:00 and excludes 07:00. A deferred message has the right UTC release time, isn't released a second early, and is released exactly on time. An opt-out during the wait is honoured. A critical message goes through. The daylight-saving case gives 11:00 UTC.
- Rate limits. The N+1th is suppressed, the window slides, limits are per user, and suppressed-by-preference messages use no quota (which checks the filter order).
- Delivery. Backoff doubles. The full status history for "fail twice then succeed" is exact. A permanent error skips retries. An unknown exception is retried. All channels failing gives
FAILEDwith every attempt recorded. In-app writes to the inbox. A bounce afterSENTfails the record. - State machine. Skipping
SENDINGis refused. Terminal states refuse every move. An early receipt is buffered and applied. - Stress. 900 submits of 300 distinct keys from 12 threads across 20 users produce exactly 300 sends.
"""test_notify.py: python -m unittest test_notify -v"""
import threading
import unittest
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, time, timedelta, timezone
from notify import (Channel, FakeClock, IdempotencyConflict, IllegalTransition, Notification,
PermanentError, Priority, QuietHours, Request, Status, TransientError,
build, quiet_end, req)
NOON = datetime(2026, 11, 10, 12, 0, tzinfo=timezone.utc)
class Base(unittest.TestCase):
def setUp(self):
self.clock = FakeClock(NOON)
self.svc, self.senders, self.sleeps = build(self.clock)
def tearDown(self):
self.svc.shutdown()
def send(self, key, **kw):
n = self.svc.submit(req(key, **kw))
self.assertTrue(self.svc.wait_idle())
return n
class TemplateTests(Base):
def test_renders_every_variable(self):
self.send("t1")
msg = self.senders[Channel.EMAIL].outbox[0][1]
self.assertEqual((msg.subject, msg.body), ("Order A1 shipped", "Hi Ben, order A1 is on its way."))
def test_missing_variable_rejected_before_anything_is_stored(self):
with self.assertRaises(ValueError):
self.svc.submit(Request("t2", "ben", "order_shipped", {"name": "Ben"}, "orders", (Channel.EMAIL,)))
self.assertNotIn("t2", self.svc._by_key)
def test_channel_without_variant_rejected(self):
with self.assertRaises(ValueError):
self.svc.submit(req("t3", template="sale", channels=(Channel.PUSH,), pct="5"))
class IdempotencyTests(Base):
def test_concurrent_duplicates_send_once(self):
with ThreadPoolExecutor(16) as ex:
ids = {n.id for n in ex.map(lambda _: self.svc.submit(req("dup")), range(64))}
self.assertTrue(self.svc.wait_idle())
self.assertEqual(len(ids), 1)
self.assertEqual(len(self.senders[Channel.EMAIL].outbox), 1)
def test_key_reuse_with_other_payload_is_a_conflict(self):
self.send("dup2")
with self.assertRaises(IdempotencyConflict):
self.svc.submit(req("dup2", order="Z9"))
def test_failed_notification_is_not_resent_by_a_retry_of_the_request(self):
self.senders[Channel.PUSH].fail(PermanentError)
n = self.send("dup3", channels=(Channel.PUSH,))
self.assertIs(n.status, Status.FAILED)
self.assertIs(self.svc.submit(req("dup3", channels=(Channel.PUSH,))), n)
def test_provider_gets_a_stable_dedup_key(self):
self.senders[Channel.EMAIL].fail(TransientError)
n = self.send("dup4")
self.assertEqual(self.senders[Channel.EMAIL].outbox[0][2], f"{n.id}:email")
class PreferenceTests(Base):
def test_opted_out_channel_is_skipped(self):
n = self.send("p1", template="sale", category="marketing", channels=(Channel.SMS, Channel.EMAIL), pct="10")
self.assertIs(n.channel, Channel.EMAIL)
self.assertEqual(self.senders[Channel.SMS].outbox, [])
def test_category_wide_opt_out_suppresses(self):
self.svc.users["ben"].opt_outs.add("marketing:*")
n = self.svc.submit(req("p2", template="sale", category="marketing", pct="10"))
self.assertIs(n.status, Status.SUPPRESSED)
self.assertEqual(n.reason, "opted out or no address")
def test_opt_out_of_one_category_leaves_others(self):
self.svc.users["ben"].opt_outs.add("marketing:*")
self.assertIs(self.send("p3").status, Status.SENT)
def test_channel_without_address_is_skipped(self):
n = self.send("p4", channels=(Channel.IN_APP, Channel.EMAIL)) # ben has no in-app address
self.assertIs(n.channel, Channel.EMAIL)
class QuietHoursTests(Base):
def test_window_wraps_midnight(self):
q = QuietHours(time(22), time(7))
self.assertTrue(q.contains(time(23, 59)) and q.contains(time(0)) and q.contains(time(6, 59)))
self.assertFalse(q.contains(time(7)) or q.contains(time(21, 59)))
def test_deferred_until_local_end_and_released(self):
self.clock.now = datetime(2026, 11, 10, 17, 0, tzinfo=timezone.utc) # 22:30 IST
n = self.svc.submit(req("q1", user="asha"))
self.assertIs(n.status, Status.SCHEDULED)
self.assertEqual(n.not_before, datetime(2026, 11, 11, 1, 30, tzinfo=timezone.utc))
self.clock.now = n.not_before - timedelta(seconds=1)
self.assertEqual(self.svc.release_due(), 0)
self.clock.advance(seconds=1)
self.assertEqual(self.svc.release_due(), 1)
self.assertTrue(self.svc.wait_idle())
self.assertIs(n.status, Status.SENT)
def test_opt_out_while_waiting_is_honoured(self):
self.clock.now = datetime(2026, 11, 10, 17, 0, tzinfo=timezone.utc)
n = self.svc.submit(req("q2", user="asha"))
self.svc.users["asha"].opt_outs.add("orders:*")
self.clock.now = n.not_before
self.svc.release_due()
self.assertIs(n.status, Status.SUPPRESSED)
def test_critical_bypasses_quiet_hours(self):
self.clock.now = datetime(2026, 11, 10, 17, 0, tzinfo=timezone.utc)
n = self.send("q3", user="asha", priority=Priority.CRITICAL)
self.assertIs(n.status, Status.SENT)
def test_end_time_respects_daylight_saving(self):
# 23:30 EST on 7 March 2026. Clocks jump forward at 02:00, so 07:00 EDT is 11:00 UTC, not 12:00.
end = quiet_end(QuietHours(time(23), time(7)), datetime(2026, 3, 8, 4, 30, tzinfo=timezone.utc),
"America/New_York")
self.assertEqual(end, datetime(2026, 3, 8, 11, 0, tzinfo=timezone.utc))
class RateLimitTests(unittest.TestCase):
def test_limit_then_window_slides(self):
clock = FakeClock(NOON)
svc, _, _ = build(clock, rate_limit=2)
a, b, c = (svc.submit(req(f"r{i}")) for i in range(3))
self.assertIs(c.status, Status.SUPPRESSED)
clock.advance(hours=1)
d = svc.submit(req("r3"))
self.assertTrue(svc.wait_idle())
self.assertIs(d.status, Status.SENT)
svc.shutdown()
def test_limits_are_per_user(self):
svc, _, _ = build(FakeClock(NOON), rate_limit=1)
svc.submit(req("u1"))
self.assertIsNot(svc.submit(req("u2", user="asha")).status, Status.SUPPRESSED)
svc.shutdown()
def test_suppressed_by_preferences_uses_no_quota(self):
svc, _, _ = build(FakeClock(NOON), rate_limit=1)
svc.users["ben"].opt_outs.add("marketing:*")
svc.submit(req("u3", template="sale", category="marketing", pct="1"))
self.assertIsNot(svc.submit(req("u4")).status, Status.SUPPRESSED)
svc.shutdown()
class DeliveryTests(Base):
def test_backoff_doubles(self):
self.senders[Channel.PUSH].fail(TransientError, 2)
n = self.send("d1", channels=(Channel.PUSH,))
self.assertEqual(self.sleeps, [0.5, 1.0])
self.assertEqual(n.history, [Status.QUEUED, Status.SENDING, Status.RETRYING, Status.SENDING,
Status.RETRYING, Status.SENDING, Status.SENT])
def test_permanent_error_skips_retries(self):
self.senders[Channel.PUSH].fail(PermanentError)
n = self.send("d2", channels=(Channel.PUSH, Channel.SMS))
self.assertEqual((n.channel, self.sleeps), (Channel.SMS, []))
def test_unknown_exception_is_retried(self):
self.senders[Channel.PUSH].fail(KeyError)
self.assertIs(self.send("d3", channels=(Channel.PUSH,)).status, Status.SENT)
def test_all_channels_fail(self):
self.senders[Channel.PUSH].fail(TransientError, 3)
self.senders[Channel.SMS].fail(PermanentError)
n = self.send("d4", channels=(Channel.PUSH, Channel.SMS))
self.assertIs(n.status, Status.FAILED)
self.assertEqual(len(n.attempts), 4)
def test_in_app_writes_to_inbox(self):
self.send("d5", user="asha", channels=(Channel.IN_APP,))
self.assertEqual(len(self.senders[Channel.IN_APP].inbox["asha"]), 1)
def test_bounce_after_sent_fails(self):
n = self.send("d6")
self.svc.on_receipt(n.id, delivered=False)
self.assertEqual((n.status, n.reason), (Status.FAILED, "bounced"))
class StateMachineTests(unittest.TestCase):
def n(self):
return Notification(req("s"), build(FakeClock(NOON))[0].users["ben"])
def test_cannot_skip_sending(self):
with self.assertRaises(IllegalTransition):
self.n().move(Status.SENT)
def test_terminal_states_are_final(self):
n = self.n()
n.move(Status.SUPPRESSED)
for s in Status:
with self.assertRaises(IllegalTransition):
n.move(s)
def test_receipt_before_sent_is_buffered(self):
n = self.n()
n.move(Status.SENDING)
n.receipt(True)
self.assertIs(n.status, Status.SENDING)
n.mark_sent(Channel.EMAIL)
self.assertIs(n.status, Status.DELIVERED)
class StressTest(unittest.TestCase):
def test_many_threads_many_users(self):
svc, senders, _ = build(FakeClock(NOON), workers=8)
for i in range(20):
svc.users[f"u{i}"] = type(svc.users["ben"])(f"u{i}", "UTC", {Channel.EMAIL: f"u{i}@x"})
keys = [f"s{i % 300}" for i in range(900)] # every key submitted three times
with ThreadPoolExecutor(12) as ex:
list(ex.map(lambda k: svc.submit(req(k, user=f"u{int(k[1:]) % 20}")), keys))
self.assertTrue(svc.wait_idle(10))
self.assertEqual(len(senders[Channel.EMAIL].outbox), 300)
svc.shutdown()
if __name__ == "__main__":
unittest.main()
Run it with python -m unittest test_notify -v. All 29 tests run in well under a second, because nothing sleeps.
10. Common mistakes
- Sending synchronously inside
submit. The caller's request now takes as long as the slowest provider, and a provider outage becomes an outage of every service that sends notifications. Queue and return. - Checking idempotency with "contains, then put". Two threads both see "missing" and both send. The check and the insert must be one atomic operation.
- Generating the idempotency key inside the service. A random id per call protects against nothing, because a retry gets a new id. The key must come from the caller and describe the intent.
- Storing the key only after a successful send. Then a retry during a slow send goes through, and a failed send can be retried into a duplicate later. Store the key when you accept the request.
- Quiet hours in server time. "No messages between 22:00 and 07:00" means the user's 22:00. Storing a UTC offset instead of a zone name (
+05:30instead ofAsia/Kolkata) also breaks, twice a year, for every user in a zone with daylight saving. - Forgetting that windows wrap midnight.
start <= t < endis always false for 22:00 to 07:00. - Dropping instead of deferring during quiet hours. The user wanted their order update, just not at 3 a.m. Defer non-urgent messages and let critical ones through.
- Retrying everything the same way. A permanent error retried three times wastes a worker. A transient error treated as permanent loses a message. Classify errors in the sender, which is the only place that knows the provider's codes.
- Retrying without backoff, or without jitter at scale. Immediate retries hammer a provider that's already struggling. When thousands of notifications fail at the same moment, identical backoff schedules retry at the same moment too. Add random jitter. Timeouts, retries and backoff has the details.
- Merging
SENTandDELIVERED. There's then nowhere to record a bounce and no way to measure provider delivery rates. - Status as booleans.
isSent,isDelivered,isFailedallow combinations that make no sense, and every reader has to guess which flag wins. - Holding a lock while calling a provider. One slow SMS call blocks every other notification behind that lock.
- Testing with real sleeps. A suite that sleeps through backoffs takes minutes and fails randomly on a loaded CI machine. Inject the clock and the sleep.
- Rate limiting before the other filters. Messages that were never going to be sent use up the quota.
- A subclass per channel for notifications. The channel can change during delivery through fallback, and an object can't change its class.
The Common LLD Mistakes page covers the general versions of several of these.
11. Interview follow-ups
"Is this exactly-once delivery?"
No, and it can't be. Our side guarantees at most one record per key and at most one successful send call per record. But a crash between the provider accepting the message and us recording SENT leaves the record in SENDING. A recovery job must either resend, which may duplicate, or give up, which may lose the message. The provider dedup key closes most of that gap for providers that support it. For those that don't, choose based on the message. A duplicate "your order shipped" email is harmless. A duplicate "you've been charged" SMS generates support tickets. Nobody can promise exactly-once to a phone screen. Exactly-once semantics explains why in general.
"How do you pick the idempotency key?"
From the business event, not the delivery attempt: order-shipped:{orderId} or password-reset:{userId}:{tokenId}. Two different events must never share a key, so order-shipped:{userId} is wrong, because the user's second order would be silently swallowed. The conflict check (same key, different request) catches exactly that bug in testing.
"Where do quiet hours end when the user travels?"
The zone is a user setting, so it's wherever the user's profile says. Mobile apps often update the zone from the device automatically. The subtle case is a message deferred under the old zone. Our design computes notBefore once, at deferral. When it's released, the whole filter chain runs again under the current settings, so if the new zone puts the user back inside quiet hours, it's deferred again. Self-correcting, with no special code.
"What happens to a burst of 10 million marketing notifications?"
The pool caps concurrency, but the queue in front of it is unbounded in this design, so 10 million records sit in memory. Two changes: bound the queue and push back on the producer (block or reject the bulk sender, never the OTP sender), and give critical and bulk traffic separate pools so a campaign can't delay a login code. At real scale this becomes an HLD problem, with a durable queue and per-provider throughput limits, and Design a Notification System covers that. The class design doesn't change. The queue behind admit does.
"How would you make the rate limiter fairer, or cheaper?"
The sliding-window log is exact but stores one timestamp per message per user. A token bucket stores two numbers per user and allows short bursts, which matches how people perceive "too many notifications". A sliding-window counter approximates the log with two counters. All three fit behind the same Filter interface. The rate limiter material compares them.
"Should rate-limited notifications be dropped or delayed?"
It depends on the category, which is why it's a policy. A marketing message that's rate limited can be dropped, since a later one will do. A social notification is better rolled into a digest (Extension B). A transactional message shouldn't be rate limited at all in practice, which is why this design exempts critical priority. A good answer names the categories and assigns a policy to each.
"How do you test the time-zone logic properly?"
Pick instants on either side of a daylight-saving change in zones that have one (New York, London), in a zone with a half-hour offset (Kolkata), and in one with a 45-minute offset (Kathmandu). Assert the exact UTC result, as the DST test above does. Also test a window that ends exactly at the current minute, and one where start == end. That last one is either "always quiet" or "never quiet" depending on your definition, so decide which and test it.
"Why does the worker render the template, not submit?"
Because of deferral. A message deferred for eight hours renders when it's sent, with the current template. If templates are versioned and you want the version the caller saw, store the template version on the request. That's a one-field change, and it's worth asking the interviewer which behaviour they want.
"How would you add a user-facing notification history?"
The records are the history. Add an index by user id (a map from user to a list of record ids) and a query method that returns records newest first, with status and channel. The in-app channel already writes an inbox. Keep the two separate: the inbox is content the user reads, the history is an audit log of what the system did.
"What changes if senders are asynchronous, returning futures?"
The delivery loop becomes a chain of callbacks or an async function, as in the TypeScript version. The rules don't change. What changes is that a worker is no longer pinned during a send, so one thread can drive many deliveries, and the early-receipt race becomes more likely, which the record already handles.
Related
- Design a Pub-Sub / Message Broker is the natural transport in front of this service.
- Design a Task Scheduler builds the delay queue that would replace the sleeping retry and the scheduled list.
- Strategy, Chain of Responsibility, Decorator and State cover the patterns used here in depth.
- Notification patterns and Design a Notification System cover the distributed version.
- Dead-letter queues is where failed notifications go in a production pipeline.