Skip to content

High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.

Fix campaign resume checkpoints to avoid skipping unsent subscribers

Kailash Nadha729a4a6d635
diff --git a/.playwright-mcp/console-2026-04-30T05-12-01-830Z.log b/.playwright-mcp/console-2026-04-30T05-12-01-830Z.log
new file mode 100644
index 00000000..b7390366
--- /dev/null
+++ b/.playwright-mcp/console-2026-04-30T05-12-01-830Z.log
@@ -0,0 +1,3 @@
+[ 137466ms] [ERROR] Failed to load resource: net::ERR_CONNECTION_REFUSED @ http://localhost:9000/api/events?type=error:0
+[ 140470ms] [ERROR] Failed to load resource: net::ERR_CONNECTION_REFUSED @ http://localhost:9000/api/events?type=error:0
+[ 143474ms] [ERROR] Failed to load resource: net::ERR_CONNECTION_REFUSED @ http://localhost:9000/api/events?type=error:0
diff --git a/cmd/manager_store.go b/cmd/manager_store.go
index c704737e..5b1458ee 100644
--- a/cmd/manager_store.go
+++ b/cmd/manager_store.go
@@ -18,11 +18,10 @@ type store struct {
}
type runningCamp struct {
- CampaignID int `db:"campaign_id"`
- CampaignType string `db:"campaign_type"`
- LastSubscriberID int `db:"last_subscriber_id"`
- MaxSubscriberID int `db:"max_subscriber_id"`
- ListID int `db:"list_id"`
+ CampaignID int `db:"campaign_id"`
+ CampaignType string `db:"campaign_type"`
+ MaxSubscriberID int `db:"max_subscriber_id"`
+ ListID int `db:"list_id"`
}
func newManagerStore(q *models.Queries, c *core.Core, m media.Store) *store {
@@ -34,11 +33,11 @@ func newManagerStore(q *models.Queries, c *core.Core, m media.Store) *store {
}
// NextCampaigns retrieves active campaigns ready to be processed excluding
-// campaigns that are also being processed. Additionally, it takes a map of campaignID:sentCount
-// of campaigns that are being processed and updates them in the DB.
-func (s *store) NextCampaigns(currentIDs []int64, sentCounts []int64) ([]*models.Campaign, error) {
+// campaigns that are also being processed. It also persists sent counts and
+// resume checkpoints for campaigns being processed.
+func (s *store) NextCampaigns(currentIDs []int64, sentCounts []int64, lastSubIDs []int64) ([]*models.Campaign, error) {
var out []*models.Campaign
- err := s.queries.NextCampaigns.Select(&out, pq.Int64Array(currentIDs), pq.Int64Array(sentCounts))
+ err := s.queries.NextCampaigns.Select(&out, pq.Int64Array(currentIDs), pq.Int64Array(sentCounts), pq.Int64Array(lastSubIDs))
return out, err
}
@@ -46,7 +45,7 @@ func (s *store) NextCampaigns(currentIDs []int64, sentCounts []int64) ([]*models
// Since batches are processed sequentially, the retrieval is ordered by ID,
// and every batch takes the last ID of the last batch and fetches the next
// batch above that.
-func (s *store) NextSubscribers(campID, limit int) ([]models.Subscriber, error) {
+func (s *store) NextSubscribers(campID, lastFetchedID, limit int) ([]models.Subscriber, error) {
var camps []runningCamp
if err := s.queries.GetRunningCampaign.Select(&camps, campID); err != nil {
return nil, err
@@ -62,7 +61,7 @@ func (s *store) NextSubscribers(campID, limit int) ([]models.Subscriber, error)
}
var out []models.Subscriber
- err := s.queries.NextCampaignSubscribers.Select(&out, camps[0].CampaignID, camps[0].CampaignType, camps[0].LastSubscriberID, camps[0].MaxSubscriberID, pq.Array(listIDs), limit)
+ err := s.queries.NextCampaignSubscribers.Select(&out, camps[0].CampaignID, camps[0].CampaignType, lastFetchedID, camps[0].MaxSubscriberID, pq.Array(listIDs), limit)
return out, err
}
diff --git a/internal/manager/manager.go b/internal/manager/manager.go
index 72e8e109..fb2c99da 100644
--- a/internal/manager/manager.go
+++ b/internal/manager/manager.go
@@ -47,8 +47,8 @@ const (
// Store represents a data backend, such as a database,
// that provides subscriber and campaign records.
type Store interface {
- NextCampaigns(currentIDs []int64, sentCounts []int64) ([]*models.Campaign, error)
- NextSubscribers(campID, limit int) ([]models.Subscriber, error)
+ NextCampaigns(currentIDs []int64, sentCounts []int64, lastSubIDs []int64) ([]*models.Campaign, error)
+ NextSubscribers(campID, lastFetchedID, limit int) ([]models.Subscriber, error)
GetCampaign(campID int) (*models.Campaign, error)
GetAttachment(mediaID int) (models.Attachment, error)
GetInlineAttachmentByFilename(filename string) (models.Attachment, string, error)
@@ -560,15 +560,15 @@ func (m *Manager) worker() {
// and stops the campaign if the error count exceeds the threshold.
msg.pipe.OnError()
} else {
- id := uint64(msg.Subscriber.ID)
- if id > msg.pipe.lastID.Load() {
- msg.pipe.lastID.Store(uint64(msg.Subscriber.ID))
- }
msg.pipe.rate.Incr(1)
msg.pipe.sent.Add(1)
}
- // Mark the message as done.
+ // Retain failed sends only when stopped, allowing retry on resume.
+ // Otherwise, send errors are considered processed and are not retried.
+ if err == nil || !msg.pipe.stopped.Load() {
+ msg.pipe.completeSub(msg.Subscriber.ID)
+ }
msg.pipe.wg.Done()
}
@@ -595,11 +595,13 @@ func (m *Manager) nextCampaigns() ([]*models.Campaign, error) {
// Needs to pass empty slices in case there are no campaigns.
var (
- ids = make([]int64, 0, len(m.pipes))
- counts = make([]int64, 0, len(m.pipes))
+ ids = make([]int64, 0, len(m.pipes))
+ counts = make([]int64, 0, len(m.pipes))
+ lastIDs = make([]int64, 0, len(m.pipes))
)
for _, p := range m.pipes {
ids = append(ids, int64(p.camp.ID))
+ lastIDs = append(lastIDs, int64(p.getCheckpoint()))
// Get the sent counts for campaigns and reset them to 0
// as in the database, they're stored cumulatively (sent += $newSent).
@@ -610,7 +612,7 @@ func (m *Manager) nextCampaigns() ([]*models.Campaign, error) {
// A returned error does not guarantee the writes in the query were rolled back.
// The sent count shouldn't be restored, which could result in double sends.
- return m.store.NextCampaigns(ids, counts)
+ return m.store.NextCampaigns(ids, counts, lastIDs)
}
// trackLink register a URL and return its UUID to be used in message templates
diff --git a/internal/manager/pipe.go b/internal/manager/pipe.go
index 91dd05f8..c8a49d40 100644
--- a/internal/manager/pipe.go
+++ b/internal/manager/pipe.go
@@ -15,11 +15,14 @@ type pipe struct {
rate *ratecounter.RateCounter
wg *sync.WaitGroup
sent atomic.Int64
- lastID atomic.Uint64
errors atomic.Uint64
stopped atomic.Bool
withErrors atomic.Bool
+ lastFetched int
+ pending map[int]struct{}
+ pendingMut sync.Mutex
+
m *Manager
}
@@ -48,7 +51,10 @@ func (m *Manager) newPipe(c *models.Campaign) (*pipe, error) {
// Add the campaign to the active map.
p := &pipe{
- camp: c,
+ camp: c,
+ lastFetched: c.LastSubscriberID,
+ pending: make(map[int]struct{}),
+
rate: ratecounter.NewRateCounter(time.Minute),
wg: &sync.WaitGroup{},
m: m,
@@ -79,8 +85,12 @@ func (m *Manager) newPipe(c *models.Campaign) (*pipe, error) {
// in the current batch or not. A false indicates that all subscribers
// have been processed, or that a campaign has been paused or cancelled.
func (p *pipe) NextSubscribers() (bool, error) {
+ if p.stopped.Load() {
+ return false, nil
+ }
+
// Fetch the next batch of subscribers from a 'running' campaign.
- subs, err := p.m.store.NextSubscribers(p.camp.ID, p.m.cfg.BatchSize)
+ subs, err := p.m.store.NextSubscribers(p.camp.ID, p.lastFetched, p.m.cfg.BatchSize)
if err != nil {
return false, fmt.Errorf("error fetching campaign subscribers (%s): %v", p.camp.Name, err)
}
@@ -91,6 +101,14 @@ func (p *pipe) NextSubscribers() (bool, error) {
return false, nil
}
+ // Record all fetched subs before queueing for messaging.
+ p.pendingMut.Lock()
+ p.lastFetched = subs[len(subs)-1].ID
+ for _, s := range subs {
+ p.pending[s.ID] = struct{}{}
+ }
+ p.pendingMut.Unlock()
+
// Is there a sliding window limit configured?
hasSliding := p.m.cfg.SlidingWindow &&
p.m.cfg.SlidingWindowRate > 0 &&
@@ -98,9 +116,14 @@ func (p *pipe) NextSubscribers() (bool, error) {
// Push messages.
for _, s := range subs {
+ if p.stopped.Load() {
+ return false, nil
+ }
+
msg, err := p.newMessage(s)
if err != nil {
p.m.log.Printf("error rendering message (%s) (%s): %v", p.camp.Name, s.Email, err)
+ p.completeSub(s.ID)
continue
}
@@ -186,6 +209,27 @@ func (p *pipe) newMessage(s models.Subscriber) (CampaignMessage, error) {
return msg, nil
}
+// completeSub removes a processed subscriber message.
+func (p *pipe) completeSub(id int) {
+ p.pendingMut.Lock()
+ delete(p.pending, id)
+ p.pendingMut.Unlock()
+}
+
+// getCheckpoint returns the ID of the last processed subscriber message,
+// ensuring that no queued or in-process messages are skipped.
+func (p *pipe) getCheckpoint() int {
+ p.pendingMut.Lock()
+ defer p.pendingMut.Unlock()
+
+ id := p.lastFetched
+ for pending := range p.pending {
+ id = min(id, pending-1)
+ }
+
+ return id
+}
+
// cleanup finishes the campaign and updates the campaign status in the DB
// and also triggers a notification to the admin. This only triggers once
// a pipe's wg counter is fully exhausted, draining all messages in its queue.
@@ -200,7 +244,7 @@ func (p *pipe) cleanup() {
// Swap prevents later scans from counting these sends again while the pipe
// remains in the map.
p.m.countsMut.Lock()
- err := p.m.store.UpdateCampaignCounts(p.camp.ID, 0, int(p.sent.Swap(0)), int(p.lastID.Load()))
+ err := p.m.store.UpdateCampaignCounts(p.camp.ID, 0, int(p.sent.Swap(0)), p.getCheckpoint())
p.m.countsMut.Unlock()
if err != nil {
p.m.log.Printf("error updating campaign counts (%s): %v", p.camp.Name, err)
diff --git a/models/campaigns.go b/models/campaigns.go
index a0e94fac..7280bc9b 100644
--- a/models/campaigns.go
+++ b/models/campaigns.go
@@ -76,10 +76,11 @@ type Campaign struct {
ArchiveSlug null.String `db:"archive_slug" json:"archive_slug"`
ArchiveTemplateID null.Int `db:"archive_template_id" json:"archive_template_id"`
ArchiveMeta json.RawMessage `db:"archive_meta" json:"archive_meta"`
+ LastSubscriberID int `db:"last_subscriber_id" json:"-"`
// TemplateBody is joined in from templates by the next-campaigns query.
- TemplateBody string `db:"template_body" json:"-"`
- ArchiveTemplateBody string `db:"archive_template_body" json:"-"`
+ TemplateBody string `db:"template_body" json:"-"`
+ ArchiveTemplateBody string `db:"archive_template_body" json:"-"`
Tpl *tplRenderer `json:"-"`
SubjectTpl *tplRenderer `json:"-"`
FromEmailTpl *tplRenderer `json:"-"`
diff --git a/queries/campaigns.sql b/queries/campaigns.sql
index 265059c5..a6366ce1 100644
--- a/queries/campaigns.sql
+++ b/queries/campaigns.sql
@@ -173,10 +173,10 @@ SELECT EXISTS (
);
-- name: next-campaigns
--- Retreives campaigns that are running (or scheduled and the time's up) and need
+-- Retrieves campaigns that are running (or scheduled and the time's up) and need
-- to be processed. It updates the to_send count and max_subscriber_id of the campaign,
-- that is, the total number of subscribers to be processed across all lists of a campaign.
--- Thus, it has a sideaffect.
+-- Also saves sent counts and resume checkpoints for active campaigns.
-- In addition, it finds the max_subscriber_id, the upper limit across all lists of
-- a campaign. This is used to fetch and slice subscribers for the campaign in next-campaign-subscribers.
WITH camps AS (
@@ -215,9 +215,9 @@ counts AS (
GROUP BY camps.id
),
updateCounts AS (
- WITH uc (campaign_id, sent_count) AS (SELECT * FROM unnest($1::INT[], $2::INT[]))
+ WITH uc (campaign_id, sent_count, last_sub_id) AS (SELECT * FROM unnest($1::INT[], $2::INT[], $3::INT[]))
UPDATE campaigns
- SET sent = sent + uc.sent_count
+ SET sent = sent + uc.sent_count, last_subscriber_id = GREATEST(campaigns.last_subscriber_id, uc.last_sub_id)
FROM uc WHERE campaigns.id = uc.campaign_id
),
u AS (
@@ -298,17 +298,15 @@ SELECT link_clicks.campaign_id,
-- name: get-running-campaign
-- Returns the metadata for a running campaign that is required by next-campaign-subscribers to retrieve
-- a batch of campaign subscribers for processing.
-SELECT campaigns.id AS campaign_id, campaigns.type as campaign_type, last_subscriber_id, max_subscriber_id, lists.id AS list_id
+SELECT campaigns.id AS campaign_id, campaigns.type as campaign_type, max_subscriber_id, lists.id AS list_id
FROM campaigns
JOIN campaign_lists ON (campaign_lists.campaign_id = campaigns.id)
JOIN lists ON (lists.id = campaign_lists.list_id)
WHERE campaigns.id = $1 AND campaigns.status='running';
-- name: next-campaign-subscribers
--- Returns a batch of subscribers in a given campaign starting from the last checkpoint
--- (last_subscriber_id). Every fetch updates the checkpoint and the sent count, which means
--- every fetch returns a new batch of subscribers until all rows are exhausted.
---
+-- Returns a batch of subscribersafter the runtime cursor ($3). last_subscriber_id is updated
+-- based on actual sends and not mere fetch.
-- In previous versions, get-running-campaign + this was a single query spread across multiple
-- CTEs, but despite numerous permutations and combinations, Postgres query planner simply would not use
-- the right indexes on subscriber_lists when the JOIN or ids were referenced dynamically from campLists
@@ -330,7 +328,7 @@ subs AS (
JOIN subscribers s ON s.id = sl.subscriber_id
WHERE
sl.list_id = ANY($5::INT[])
- -- last_subscriber_id
+ -- In-memory fetch cursor.
AND s.id > $3
-- max_subscriber_id
AND s.id <= $4
@@ -352,11 +350,6 @@ subs AS (
)
ORDER BY s.id LIMIT $6
) subIDs JOIN subscribers s ON (s.id = subIDs.id) ORDER BY s.id
-),
-u AS (
- UPDATE campaigns
- SET last_subscriber_id = (SELECT MAX(id) FROM subs), updated_at = NOW()
- WHERE (SELECT COUNT(id) FROM subs) > 0 AND id=$1
)
SELECT * FROM subs;
@@ -425,7 +418,7 @@ INSERT INTO campaign_lists (campaign_id, list_id, list_name)
UPDATE campaigns SET
to_send=(CASE WHEN $2 != 0 THEN $2 ELSE to_send END),
sent=sent+$3,
- last_subscriber_id=(CASE WHEN $4 > 0 THEN $4 ELSE last_subscriber_id END),
+ last_subscriber_id=GREATEST(last_subscriber_id, $4),
updated_at=NOW()
WHERE id=$1;