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 ¶
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.
const MaxHour = 720
MaxHour is the last hour campaign_hourly keeps (30 days).
const Version = 1
Version of the counting rules. Campaigns rebuilt with an older version are rebuilt again by the rebuild sweep.
Variables ¶
var ErrNotFound = errors.New("counters: campaign not found")
ErrNotFound means the campaign doesn't exist.
Functions ¶
func HourOf ¶
HourOf is the hour after start an event happened in, as campaign_hourly keeps it (0 to MaxHour).
func Unsubscribed ¶
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 ¶
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).
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) Click ¶
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.
type Moved ¶
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 ¶
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.