counters

package
v1.6.0 Latest Latest
Warning

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

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

Documentation

Overview

Package counters keeps a campaign's report counters (campaign_counters, campaign_hourly, the clicks of campaign_links and the breakdowns of campaign_dims) 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 (
	DimClient  = "client"
	DimOS      = "os"
	DimDevice  = "device"
	DimCountry = "country"
	DimCity    = "city"
	DimHour    = "hour"
	DimWeekday = "weekday"
)

Breakdowns (campaign_dims.dim): a campaign's human opens and clicks by the mail client, system, device, country and city of each person's first engagement, and by the local hour and weekday of the first human open (opens) and of the first click (clicks).

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 CityKey

func CityKey(country, city string) string

CityKey is a city's campaign_dims key: "CC|City".

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 Dims

type Dims struct {
	Client, OS, Device, Country, City string
	HumanLocal, ClickLocal            *int16
}

Dims are what a message keeps of its first human engagement on a campaign that records breakdowns (campaigns.breakdown): the client, system and device (internal/tracking ClientParts keys), the country code and English city name (empty when unknown), and the local weekday-hours ((ISO weekday-1)*24 + hour, 0-167, in the workspace's time zone at that moment) of the first human open and of the first click. Tracking passes the strings; the locals come back from CountersMoveEngagement.

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: its counters, hours and, on a campaign that records breakdowns, the breakdowns of a first human open or a first click.

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, then breakdowns, 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
	Breakdown bool
	Dims      Dims
}

Moved is a message's move as CountersMoveDelivery and CountersMoveEngagement return it. Breakdown says the campaign records breakdowns, Dims what the message keeps for them (engagement only).

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: the same move as a delivery's, with the breakdowns the message keeps.

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, clicks per link and, when it records them, breakdowns 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. Breakdowns count what messages keep now: a place erased with a reader's IP or cleared by retention leaves the rebuilt totals, though the live ones kept it.

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