counters

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package counters keeps a campaign's report counters (campaign_counters, campaign_hourly and the clicks of campaign_links) in step with its messages (review AN-3).

A counter is a function of message states, not a tally of events: a message counts as delivered when it has a delivery and no hard bounce, as soft-bounced while a soft bounce isn't followed by a delivery, as deferred once however often it was deferred, and its opens fall in exactly one of three buckets (a person's, a privacy proxy's, a scanner's). So counters change only when a message's state does: a redelivered webhook, a soft bounce followed by a delivery or a machine open followed by a person's move each message from one bucket to another instead of counting twice, and the counters can always be rebuilt from the stored states and events (Rebuild).

Writers move a message with a statement that returns its state before and after (CountersMoveDelivery, CountersMoveEngagement), give both states to a Ledger and Flush it at the end of their transaction. Flush applies the changes in one lock order: campaign_counters rows, then campaign_hourly, then campaign_links, each in key order, always after the message rows the writer locked. Writers lock messages in id order (sort a batch before applying it), so two writers never wait for each other in a cycle.

Index

Constants

View Source
const (
	// SkipImported: history imported from another platform has its final
	// numbers but no message per recipient.
	SkipImported = "imported"
	// SkipNoHistory: fewer messages are stored than the counters count
	// (sample data), so a rebuild would lose numbers.
	SkipNoHistory = "no_history"
	// SkipNotStarted: nothing was sent.
	SkipNotStarted = "not_started"
)

Why a campaign's counters can't be rebuilt.

View Source
const MaxHour = 720

MaxHour is the last hour campaign_hourly keeps (30 days).

View Source
const Version = 1

Version of the counting rules. Campaigns rebuilt with an older version are rebuilt again by the rebuild sweep.

Variables

View Source
var ErrNotFound = errors.New("counters: campaign not found")

ErrNotFound means the campaign doesn't exist.

Functions

func HourOf

func HourOf(start, at time.Time) int

HourOf is the hour after start an event happened in, as campaign_hourly keeps it (0 to MaxHour).

func Unsubscribed

func Unsubscribed(ctx context.Context, q *store.Queries, message uuid.UUID, at time.Time) error

Unsubscribed records that a reader unsubscribed from a message (the unsubscribe page, one-click, or the provider's own unsubscribe): the message moves once, and its campaign's unsubscribe count with it.

Types

type Cell

type Cell struct {
	Campaign uuid.UUID
	Provider uuid.UUID
	Mailbox  string
	Variant  string
}

Cell is one campaign_counters row: a campaign's messages through one sending provider, to one mailbox provider, in one A/B variant.

type Delta

type Delta struct {
	Sent, Delivered, Deferred, HardBounced, SoftBounced, Complained, Rejected int64
	OpenedHuman, OpenedPrivacy, OpenedMachine, Clicked, Unsubscribed          int64
}

Delta is a change of one counter cell (or the counters of a message).

func Diff

func Diff(before, after State) Delta

Diff is what moving a message from one state to another changes.

func (Delta) Zero

func (d Delta) Zero() bool

Zero reports whether the delta changes nothing.

type Flags

type Flags struct {
	// Sent: the provider took the message (a provider that refuses it
	// afterwards takes it back out: it was never attempted).
	Sent bool
	// Delivered: a delivery event, and no hard bounce since; a complaint
	// proves delivery too.
	Delivered bool
	// Deferred: deferred at least once (once per message).
	Deferred bool
	// HardBounced and Complained follow the status.
	HardBounced bool
	Complained  bool
	// SoftBounced: a soft bounce that no delivery, hard bounce or
	// complaint followed.
	SoftBounced bool
	// Rejected: the provider refused it, when it was handed over or later.
	Rejected bool
	// Opens fall in one bucket: a person's (a click counts), else a privacy
	// proxy's (whether a person read it can't be measured), else a
	// scanner's.
	OpenedHuman   bool
	OpenedPrivacy bool
	OpenedMachine bool
	Clicked       bool
	Unsubscribed  bool
}

Flags are the counters a message counts in. The rules are the same as CountersRebuildCells' (internal/store/queries/counters.sql).

type Hours

type Hours struct {
	Human, Privacy, Machine, Clicked *int
}

Hours are the hours after the send started in which a state's engagement counts in campaign_hourly (nil: it doesn't count there).

type Ledger

type Ledger struct {
	// contains filtered or unexported fields
}

Ledger collects counter changes during a transaction and applies them in one lock order (Flush). The zero value is ready to use.

func (*Ledger) Add

func (l *Ledger) Add(m Moved)

Add records a move.

func (*Ledger) Click

func (l *Ledger) Click(campaign uuid.UUID, position int, variant string, bot, unique bool)

Click records a click on a campaign's link: a person's (unique is their first click on that link) or a bot's. variant is the A/B variant the message had ("" without a test): each variant has its click map.

func (*Ledger) Empty

func (l *Ledger) Empty() bool

Empty reports whether the ledger has nothing to apply.

func (*Ledger) Flush

func (l *Ledger) Flush(ctx context.Context, q *store.Queries) error

Flush applies what the ledger collected: counter cells, then hours, then links, then links per variant, each in key order, and empties it.

func (*Ledger) Move

func (l *Ledger) Move(c Cell, started *time.Time, before, after State)

Move records a message moving from one state to another: the counters of its cell and, when the campaign has started, its hourly engagement.

type Moved

type Moved struct {
	Cell    Cell
	Started *time.Time
	Before  State
	After   State
}

Moved is a message's move as CountersMoveDelivery and CountersMoveEngagement return it.

func FromDelivery

func FromDelivery(r store.CountersMoveDeliveryRow) Moved

FromDelivery reads a CountersMoveDelivery row.

func FromEngagement

func FromEngagement(r store.CountersMoveEngagementRow) Moved

FromEngagement reads a CountersMoveEngagement row.

type Result

type Result struct {
	Rebuilt bool
	Skipped string
}

Result says what a rebuild did.

func Rebuild

func Rebuild(ctx context.Context, pool *pgxpool.Pool, campaign uuid.UUID, now time.Time) (Result, error)

Rebuild recomputes a campaign's counters, hourly engagement and clicks per link from its messages and their stored events, in one transaction: the states the status can't tell apart are filled from the events first, then every counter is replaced by what the states add up to. Writers that move the campaign's messages meanwhile wait for it (it locks the counter rows first). A campaign whose per-message history isn't stored is left as it is, with the reason.

type State

type State struct {
	Status          string
	SentAt          *time.Time
	DeliveredAt     *time.Time
	DeferredAt      *time.Time
	SoftBouncedAt   *time.Time
	OpenedAt        *time.Time
	HumanOpenedAt   *time.Time
	PrivacyOpenedAt *time.Time
	ClickedAt       *time.Time
	UnsubscribedAt  *time.Time
}

State is what decides where a message counts.

func (State) Flags

func (s State) Flags() Flags

Flags returns the counters a state counts in.

func (State) HoursOf

func (s State) HoursOf(start time.Time) Hours

HoursOf places a state's engagement in the hours after start.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL