Queue and scale

Notifications run on VitNode's database-backed queue and cron. No extra service is needed: a working queue worker is all it takes.

Queue tasksCopy Anchor Link

All three belong to @vitnode/core and show up in AdminCP → Advanced → Queue.

Cron jobsCopy Anchor Link

The queue worker itself runs every minute. Without a cron adapter nothing moves in the background - see Troubleshooting.

Batched fan-outCopy Anchor Link

The fan-out task works through candidates in batches of fanoutBatchSize (default 500, from 10 to 5,000 - see Configuration), in the order your recipients list gives them. Duplicates are dropped before the first batch.

Each batch is one short transaction that:

1. locks the event row;
2. filters the batch - deleted users, opted-out users, one access call;
3. locks the batch's user state rows;
4. writes receipts, inbox items, unread counts and immediate email deliveries;
5. saves the cursor on the event.

Realtime messages go out after the batch commits. A crash loses at most the batch in flight, and the retry resumes after the last committed one.

Receipts make retries safe. There is one receipt per event and user, and only users with a new receipt go further. A batch that runs twice finds every receipt in place and changes nothing.

Time budget. One task stops after 20 seconds and queues a fresh task for the rest, so a 100,000-recipient announcement never blocks the queue for other work.

RecoveryCopy Anchor Link

1,000 recipients, measuredCopy Anchor Link

The integration test fanout.load.integration.test.ts publishes one event to 1,000 members plus the actor, with 200 of them listed twice and one member who switched the type off.

These numbers come from a dev container with a local PostgreSQL 16. They are indicative, not a benchmark - what matters is that queries grow per batch, not per recipient.

Lock orderingCopy Anchor Link

Every inbox write - fan-out, mark read, mark all read, remove, reconcile - locks the affected user state rows in user id order before touching anything else. Two writers that share users always take locks in the same order, so they wait for each other instead of deadlocking, and each user's inbox changes happen one at a time.

IndexesCopy Anchor Link

The migration adds the indexes the hot paths need:

RetentionCopy Anchor Link

notifications-cleanup removes, in batches:

• inbox items whose last activity is older than retentionDays (default 90, see Configuration), taking unread ones off their owner's count;
• events older than that which no inbox item points at;
• finished delivery records older than that;
• pending email for events no digest claimed within 14 days - those stop waiting for an email, and the inbox items stay.

Run it on demand from the AdminCP.

ConfigurationCopy Anchor Link

How much work each run does and how long notifications are kept are deployment decisions, so they live in your API config rather than the AdminCP. Add a notifications block to buildApiConfig in vitnode.api.config.ts:

import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  // ...
  notifications: {
    retentionDays: 30,
    fanoutBatchSize: 1000,
    emailBatchSize: 100,
    emailConcurrency: 8,
  },
})

Every key is optional:

A value outside its range is clamped to the nearest limit, and anything that isn't a whole number falls back to the default - a typo never stops notifications. Restart the API to apply a change.

The AdminCP shows the retention period in the Settings sheet but can't change it.

RelatedCopy Anchor Link