Files
HealthLog/src/lib/notifications/dispatcher.ts
T
Marc-André Bombeck fcc4e661df fix(notifications): scope client-managed suppression to the APNs leg
`medication.clientManaged` and `measurementReminder.clientManaged` mean
the iOS client schedules the reminder locally, so the server should not
push it. That is what the OpenAPI description, the settings copy and the
iOS contract all say. What the crons did was skip the dispatch entirely,
so a user who flipped the switch also lost Telegram, ntfy, webhook,
email and Web Push — channels they may well read on a desktop while the
phone holding the local schedule sits in a drawer.

Move the gate into the dispatcher's channel loop, where it applies to
APNs and nothing else. The skip is not counted as an attempt, so
`dispatched` keeps meaning "something reached the user", and it stays
countable: the same wide-event keys the crons emitted are emitted here,
plus a `skipped` row in the push-attempt ledger.

The Vorsorge path is the sharper half. It suppressed every channel and
then advanced `nextDueAt`, which dropped the reminder out of the
preventive-care card and out of the daily digest: a reminder that never
reached anyone was recorded as handled. The advance now happens only
where it always belonged, after a dispatch that a channel actually
delivered. When nothing delivers, the reminder stays overdue and visible.
2026-07-27 14:26:20 +02:00

447 lines
15 KiB
TypeScript

import { prisma } from "@/lib/db";
import { decrypt, encrypt } from "@/lib/crypto";
import type {
NotificationPayload,
TelegramChannelConfig,
NtfyChannelConfig,
WebhookChannelConfig,
EmailChannelConfig,
ChannelType,
EventType,
} from "@/lib/notifications/types";
import { EVENT_DEFAULT_ENABLED } from "@/lib/notifications/types";
import { sendViaTelegram } from "@/lib/notifications/senders/telegram";
import { sendViaNtfy } from "@/lib/notifications/senders/ntfy";
import { sendViaWebPush } from "@/lib/notifications/senders/web-push";
import { sendViaApns } from "@/lib/notifications/senders/apns";
import { sendViaWebhook } from "@/lib/notifications/senders/webhook";
import { sendViaEmail } from "@/lib/notifications/senders/email";
import type { SendOutcome } from "@/lib/notifications/retry-policy";
import {
isChannelInCooldown,
recordChannelHardReject,
recordChannelSuccess,
recordChannelTransientFailure,
} from "@/lib/notifications/channel-state";
import { getEvent } from "@/lib/logging/context";
import {
CLIENT_MANAGED_APNS_EVENTS,
hasClientManagedApnsGate,
} from "@/lib/notifications/client-managed-apns";
import { recordPushAttempt } from "@/lib/notifications/senders/push-attempt-record";
/**
* Dispatch a notification to all enabled channels for a user.
* Best-effort: logs errors but never throws.
*
* For each channel:
* 1. Skip if `enabled=false` (manually or auto-disabled).
* 2. Skip if currently in retry-cooldown (`nextRetryAt > now`).
* 3. Check the per-channel preference for this eventType (default: enabled).
* 4. Skip the APNs channel — and only that one — when the user's iOS
* client owns the local reminder for this event type.
* 5. Call the appropriate sender — which now returns a `SendOutcome` so
* the dispatcher can classify hard rejects (410, blocked-by-user) vs
* soft errors (5xx, 429, network) and update channel state accordingly.
*
* Also handles legacy Telegram config stored on the User model by
* auto-migrating it to a NotificationChannel record on first dispatch.
*/
export interface DispatchOutcome {
/** True when at least one channel reported a successful delivery. */
dispatched: boolean;
/** Channels considered after enable / cooldown / preference filtering. */
channelsAttempted: number;
/** Subset of attempted channels that returned ok. */
channelsSucceeded: number;
}
export async function dispatchNotification(
payload: NotificationPayload,
): Promise<DispatchOutcome> {
let channelsAttempted = 0;
let channelsSucceeded = 0;
try {
const channels = await prisma.notificationChannel.findMany({
where: { userId: payload.userId, enabled: true },
include: {
preferences: {
where: { eventType: payload.eventType },
},
},
});
// Check for legacy Telegram config on User model if no TELEGRAM channel exists
const hasTelegramChannel = channels.some(
(ch: { type: string }) => ch.type === "TELEGRAM",
);
if (!hasTelegramChannel) {
try {
const user = await prisma.user.findUnique({
where: { id: payload.userId },
select: {
telegramBotToken: true,
telegramChatId: true,
telegramEnabled: true,
},
});
if (
user?.telegramEnabled &&
user.telegramBotToken &&
user.telegramChatId
) {
const botToken = decrypt(user.telegramBotToken);
const channelConfig = encrypt(
JSON.stringify({ botToken, chatId: user.telegramChatId }),
);
// Auto-migrate: create NotificationChannel record
const created = await prisma.notificationChannel.upsert({
where: {
userId_type: {
userId: payload.userId,
type: "TELEGRAM",
},
},
create: {
userId: payload.userId,
type: "TELEGRAM",
enabled: true,
config: channelConfig,
},
update: {
enabled: true,
config: channelConfig,
},
include: {
preferences: {
where: { eventType: payload.eventType },
},
},
});
channels.push(created);
getEvent()?.addMeta("telegram_legacy_migration", payload.userId);
}
} catch (err) {
getEvent()?.addWarning(`Legacy Telegram migration failed: ${err}`);
}
}
// Cascade order: APNs first (if the user paired an iPhone), then
// Telegram, then ntfy, then Web Push as the universal fallback.
// The order matters because each channel is best-effort — sorting
// here keeps the payload-delivery sequence deterministic across
// dispatches even when Postgres returns rows in physical order.
channels.sort((a, b) => channelPriority(a.type) - channelPriority(b.type));
const now = new Date();
// v1.4.25 W16c — per-event default policy. Most events stay
// opt-out (no row = enabled); PERSONAL_RECORD flips to opt-in
// (no row = disabled) so the iOS backfill doesn't saturate the
// lock-screen on first launch. The user enables it explicitly
// from /settings/notifications once they've seen the badge a few
// times and decided they want push.
let defaultEnabled =
EVENT_DEFAULT_ENABLED[payload.eventType as EventType] ?? true;
// v1.7.0 — MOOD_REMINDER single source of truth = the visible card.
// The event used to default OFF, layered on top of the per-user
// `moodReminderEnabled` flag, so a user who flipped the card still
// got nothing (no pref row → `!defaultEnabled` → continue). Collapse
// the double opt-in: when the card is on, the event default is on, so
// enabling the card alone delivers. A genuine explicit per-event
// opt-out (a `NotificationPreference` row with `enabled = false`) is
// still honoured below via `pref.enabled` — only the no-row default
// is derived from the card.
if (payload.eventType === "MOOD_REMINDER") {
const user = await prisma.user.findUnique({
where: { id: payload.userId },
select: { moodReminderEnabled: true },
});
defaultEnabled = user?.moodReminderEnabled === true;
}
// Client-managed APNs suppression, resolved at most once per dispatch
// and only when an APNs channel is actually in the cascade. `null`
// means "not applicable"; the read is lazy so the common event types
// pay nothing for it.
let clientManagedApns: boolean | null = null;
const resolveClientManagedApns = async (): Promise<boolean> => {
if (clientManagedApns !== null) return clientManagedApns;
const gate = CLIENT_MANAGED_APNS_EVENTS[payload.eventType];
if (!gate) {
clientManagedApns = false;
return false;
}
const row = await prisma.user.findUnique({
where: { id: payload.userId },
select: { notificationPrefs: true },
});
clientManagedApns = gate.isClientManaged(row?.notificationPrefs);
return clientManagedApns;
};
for (const channel of channels) {
const pref = channel.preferences[0];
if (pref) {
if (!pref.enabled) continue;
} else if (!defaultEnabled) {
continue;
}
// Backoff cooldown — skip the channel until `nextRetryAt`. Without
// this guard, a flapping upstream would burn API quota every
// reminder-tick (every 60s by default), defeating the whole point
// of the exponential backoff.
if (isChannelInCooldown({ nextRetryAt: channel.nextRetryAt }, now)) {
getEvent()?.addMeta(
`notification_skip_${channel.type.toLowerCase()}_cooldown`,
channel.nextRetryAt?.toISOString() ?? "unknown",
);
continue;
}
// The iOS client owns the local banner for this event type — skip
// the server's APNs send and nothing else. Not counted as an
// attempt: no send was made, so `dispatched` keeps telling the truth
// about whether anything actually reached the user.
if (
channel.type === "APNS" &&
hasClientManagedApnsGate(payload.eventType) &&
(await resolveClientManagedApns())
) {
const gate = CLIENT_MANAGED_APNS_EVENTS[payload.eventType];
getEvent()?.addMeta(gate.metaKey, gate.tag(payload.metadata));
if (gate.detail && gate.detailKey) {
getEvent()?.addMeta(
gate.detailKey,
gate.detail(payload.userId, payload.metadata),
);
}
recordPushAttempt({
userId: payload.userId,
channel: "APNS",
eventType: payload.eventType,
result: "skipped",
reason: "client_managed",
});
continue;
}
channelsAttempted += 1;
try {
const outcome = await sendToChannel(
channel.type as ChannelType,
channel.config,
payload,
);
if (outcome.ok) {
await recordChannelSuccess({
id: channel.id,
userId: channel.userId,
type: channel.type as ChannelType,
});
channelsSucceeded += 1;
continue;
}
if (outcome.hardReject) {
await recordChannelHardReject(
{
id: channel.id,
userId: channel.userId,
type: channel.type as ChannelType,
},
outcome,
);
getEvent()?.addWarning(
`Notification channel ${channel.type} auto-disabled: ${outcome.reason}`,
);
continue;
}
const result = await recordChannelTransientFailure(
{
id: channel.id,
userId: channel.userId,
type: channel.type as ChannelType,
},
outcome,
now,
);
getEvent()?.addWarning(
`Notification dispatch failed for channel ${channel.type}: ${outcome.reason}` +
(result.autoDisabled ? " (auto-disabled after 5 failures)" : ""),
);
} catch (err) {
// Sender threw unexpectedly — treat as a soft failure so the
// backoff schedule absorbs the blip. (Senders are supposed to
// be no-throw, this is defence-in-depth.)
const message = err instanceof Error ? err.message : String(err);
await recordChannelTransientFailure(
{
id: channel.id,
userId: channel.userId,
type: channel.type as ChannelType,
},
{ reason: "sender_threw", message },
now,
);
getEvent()?.addWarning(
`Notification sender threw for ${channel.type}: ${message}`,
);
}
}
} catch (err) {
getEvent()?.addWarning(`Notification dispatcher error: ${err}`);
}
return {
dispatched: channelsSucceeded > 0,
channelsAttempted,
channelsSucceeded,
};
}
async function sendToChannel(
type: ChannelType,
encryptedConfig: string,
payload: NotificationPayload,
): Promise<SendOutcome> {
let decrypted: string;
try {
decrypted = decrypt(encryptedConfig);
} catch {
getEvent()?.addWarning(`Failed to decrypt ${type} channel config`);
// A config that can't be decrypted is a structurally-permanent failure,
// not a transient blip: the ciphertext / key pairing won't fix itself on
// a retry. Hard-reject so the channel auto-disables on first occurrence
// with an accurate reason, rather than burning the 5-failure transient
// budget and ending on the misleading `give_up_after_5_failures`. During
// a key-rotation gap every channel would otherwise auto-disable for the
// wrong reason.
return {
ok: false,
hardReject: true,
reason: `${type.toLowerCase()}_config_decrypt_failed`,
};
}
switch (type) {
case "TELEGRAM": {
let config: TelegramChannelConfig;
try {
config = JSON.parse(decrypted) as TelegramChannelConfig;
} catch {
getEvent()?.addWarning("Failed to parse Telegram channel config");
// Malformed config decodes the same on every retry — permanent.
return {
ok: false,
hardReject: true,
reason: "telegram_config_parse_failed",
};
}
return sendViaTelegram(config, payload);
}
case "NTFY": {
let config: NtfyChannelConfig;
try {
config = JSON.parse(decrypted) as NtfyChannelConfig;
} catch {
getEvent()?.addWarning("Failed to parse ntfy channel config");
// Malformed config decodes the same on every retry — permanent.
return {
ok: false,
hardReject: true,
reason: "ntfy_config_parse_failed",
};
}
return sendViaNtfy(config, payload);
}
case "WEBHOOK": {
let config: WebhookChannelConfig;
try {
config = JSON.parse(decrypted) as WebhookChannelConfig;
} catch {
getEvent()?.addWarning("Failed to parse webhook channel config");
// Malformed config decodes the same on every retry — permanent.
return {
ok: false,
hardReject: true,
reason: "webhook_config_parse_failed",
};
}
return sendViaWebhook(config, payload);
}
case "EMAIL": {
let config: EmailChannelConfig;
try {
config = JSON.parse(decrypted) as EmailChannelConfig;
} catch {
getEvent()?.addWarning("Failed to parse email channel config");
// Malformed config decodes the same on every retry — permanent.
return {
ok: false,
hardReject: true,
reason: "email_config_parse_failed",
};
}
return sendViaEmail(config, payload);
}
case "WEB_PUSH": {
return sendViaWebPush(payload.userId, payload);
}
case "APNS": {
// APNs config lives on the Device row, not in the channel config.
// The decrypt above is a no-op (config is the empty object `{}`),
// we just keep the symmetric path so future per-user overrides
// (e.g. a custom APNs topic) can hang off the channel without
// changing the dispatcher shape.
return sendViaApns(payload.userId, payload);
}
default:
getEvent()?.addWarning(`Unknown notification channel type: ${type}`);
return {
ok: false,
hardReject: false,
reason: "unknown_channel_type",
};
}
}
/**
* Static cascade order: APNs first, Web Push last. Lower number = earlier.
* The order is deliberate:
* - APNs — native iOS path; best UX when the user has an iPhone.
* - Telegram — explicit user-set chat; high deliverability.
* - ntfy — self-hosted-friendly; user controls the relay.
* - WebPush — broadest reach, slowest UX (browser must be alive).
*
* Unknown channel types sort last so they never preempt a real channel.
*/
function channelPriority(type: string): number {
switch (type) {
case "APNS":
return 0;
case "TELEGRAM":
return 1;
case "NTFY":
return 2;
// v1.17.1 — generic webhook + email sit between the self-host-friendly
// relays and Web Push: a user who configures them wants them ahead of the
// browser-must-be-alive fallback.
case "WEBHOOK":
return 3;
case "EMAIL":
return 4;
case "WEB_PUSH":
return 5;
default:
return 99;
}
}