Documentation
¶
Overview ¶
Package warmup plans and runs the warm-up of a new sending provider or dedicated IP: a daily volume ramp, the most engaged contacts first, an automatic slowdown when bounces or complaints rise, and a Broadcast share that grows with the plan (10% → 15% → 25% → 40%). The sending pipeline reads each day's cap, rate and audience tiers with Allowance.
Index ¶
- Constants
- Variables
- func CapHoldNotice(campaign, provider string, held int64, reason string, resume time.Time) (title, body i18n.Text)
- func DayOn(start time.Time, pausedAt *time.Time, now time.Time, loc *time.Location) int
- func MailboxCaps(cap int64) map[string]int64
- func MailboxOf(mbp string) string
- func OverCapToday(n int64, on *time.Time, today time.Time, loc *time.Location) int64
- func RateFor(cap int64) float64
- func Register(h huma.API, s *Service)
- func ShiftedEvent(provider string) (title, body string, texts []byte)
- func Today(ctx context.Context, q *store.Queries, providerID uuid.UUID, now time.Time, ...) *state.WarmupToday
- type Allowance
- type DailyArgs
- type DailyWorker
- type Day
- type DayStats
- type Guards
- type Hold
- type HoldStep
- type NewPlanInput
- type Plan
- type Result
- type ResumeArgs
- type ResumeWorker
- type Service
- func (s *Service) Create(ctx context.Context, ws *store.Workspace, in NewPlanInput) (WarmupPlanView, error)
- func (s *Service) DecideCapHold(ctx context.Context, ws *store.Workspace, planID, campaignID string, ...) (WarmupHoldDecisionResult, error)
- func (s *Service) Evaluate(ctx context.Context, planID uuid.UUID) error
- func (s *Service) Overview(ctx context.Context, ws *store.Workspace) (WarmupOverview, error)
- func (s *Service) ResumeCapHolds(ctx context.Context) error
- func (s *Service) SetPaused(ctx context.Context, ws *store.Workspace, id string, paused bool) (WarmupPlanView, error)
- func (s *Service) UpdateSettings(ctx context.Context, ws *store.Workspace, id string, in WarmupSettings) (WarmupPlanView, error)
- type Verdict
- type WarmupCampaignUse
- type WarmupCandidate
- type WarmupCapHold
- type WarmupHoldAlternative
- type WarmupHoldDecision
- type WarmupHoldDecisionResult
- type WarmupLogEntry
- type WarmupMailboxCap
- type WarmupOverview
- type WarmupPlanView
- type WarmupRampDay
- type WarmupRow
- type WarmupSettings
- type WarmupSlowdown
- type WarmupStep
Constants ¶
const ( // to count. CountShare = 0.8 // HealthyDays is how many counted days in a row end a slowdown's hold. HealthyDays = 2 // DefaultMinSample is the messages a day needs before the guards judge it. DefaultMinSample = 500 )
Variables ¶
var ErrTooShort = errors.New("a plan can't be shorter than the days it already counted")
ErrTooShort refuses a plan length shorter than the days it already counted.
Mailbox string Percent int }{{"gmail", 40}, {"outlook", 25}, {"yahoo", 15}, {"icloud", 10}, {"other", 10}}
MailboxShares are the parts of a day's cap per mailbox provider when a plan caps them separately: strict providers get their own lower caps.
var Tiers = []string{"active", "cooling", "at_risk", "sunset"}
Engagement tiers in order of engagement.
Functions ¶
func CapHoldNotice ¶
func CapHoldNotice(campaign, provider string, held int64, reason string, resume time.Time) (title, body i18n.Text)
CapHoldNotice is the notification a campaign's members get when today's warm-up cap (or a paused plan) holds its share on a warming provider (PR-8): kept texts, read in each member's language. reason is cap or paused; resume is when tomorrow's cap starts, in the workspace's zone.
func DayOn ¶
DayOn is a plan's day at a time, on the workspace's calendar: start is start_date (the date day 1 would have been if every day had counted; it moves on by every day that didn't count), and a paused plan stays on the day it stopped (pausedAt, nil unless the plan is paused). Callers clamp it to the plan's length.
func MailboxCaps ¶
MailboxCaps splits a day's cap per mailbox provider; the parts add up to the cap exactly (rounding goes to Gmail).
func MailboxOf ¶
MailboxOf is the warm-up bucket of a mailbox provider key (anything unknown is "other").
func OverCapToday ¶
OverCapToday is the plan's count of transactional messages sent over the cap, when it counts today (the workspace's day) and 0 otherwise.
func RateFor ¶
RateFor is the default rate for a daily cap: spread over about an hour of sending at the start, never under 1 /s.
func ShiftedEvent ¶
ShiftedEvent is the log entry the sending engine adds when a provider's share moved away during an outage and its plan repeats a day: the title and body in English, as warmup_events stores them, and the texts column that keeps their messages.
Types ¶
type Allowance ¶
type Allowance struct {
PlanID uuid.UUID
Cap int64
Sent int64
Rate float64
Tiers []string
Spread bool
// MailboxCaps and MailboxSent are today's cap and sends per mailbox
// provider (gmail, outlook, yahoo, icloud, other) when Spread.
MailboxCaps map[string]int64
MailboxSent map[string]int64
// Overflow: what's over the cap goes through a warm provider.
Overflow bool
EngagedFirst bool
Paused bool
Held bool
Day int
Days int
// NextDay is when the workspace's next day starts (a share held at
// the cap resumes then).
NextDay time.Time
}
Allowance is what a warming provider may send today: the workspace's day, whatever clock the caller keeps (PR-8). The sending pipeline sends no more than Cap-Sent messages (per mailbox provider when Spread) at Rate per second, to the listed engagement tiers, and nothing while Paused. Every stream counts toward the cap.
func AllowanceFor ¶
func AllowanceFor(ctx context.Context, q *store.Queries, providerID uuid.UUID, now time.Time, _ *time.Location) (Allowance, bool, error)
AllowanceFor returns a provider's warm-up allowance; ok is false when the provider has no running plan. The day is the workspace's: loc is ignored and kept for callers that pass theirs.
func (Allowance) MailboxLeft ¶
MailboxLeft is what the provider may still send today to one mailbox provider (the overall room when the plan doesn't spread the cap).
type DailyArgs ¶
type DailyArgs struct{}
DailyArgs evaluates every running plan: it records finished days, slows down when a guard trips, raises the Broadcast share on schedule and finishes plans.
func (DailyArgs) InsertOpts ¶
func (DailyArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type DailyWorker ¶
type Day ¶
type Day struct {
Day int `json:"day"`
Volume int64 `json:"volume"`
Rate float64 `json:"rate,omitempty"`
Share int `json:"share,omitempty"`
// Tiers are the engagement tiers the day may send to (engaged first).
Tiers []string `json:"tiers,omitempty"`
}
Day is one day of a plan's schedule.
func Ramp ¶
Ramp builds a schedule of n days from first to last emails per day, growing geometrically, with the engaged tiers first and the Broadcast share stepping up 10 → 15 → 25 → 40%.
func Reschedule ¶
Reschedule gives a plan a new length from where it stands: the days before today keep their volumes, today keeps its cap, and the rest ramps from it to the same last volume. Shortening a plan never makes today's cap jump; it only makes the coming days steeper.
type DayStats ¶
DayStats is what a warming provider sent on one of the workspace's days. Complained and Delivered count only mailbox providers that report complaints per message (review F-2): Gmail's and iCloud's mail is in neither, so their silence is never read as a 0% complaint rate.
type Guards ¶
type Guards struct {
// Bounce and Complaint are the rates (percent) that slow the plan down.
Bounce, Complaint float64
MinSample int64
// Action is what a tripped guard does: hold, step_back or pause.
Action string
}
Guards are a plan's slowdown settings.
type Hold ¶
Hold is a slowdown's hold on the cap: the cap it holds and the counted days so far.
func (Hold) After ¶
After returns the hold once a day was judged: a tripped guard holds the day's cap (or the cap of the day before it for step_back, or pauses the plan); each counted day under a hold is a healthy day, and HealthyDays in a row end it. A day that didn't count for lack of volume is no healthy day, but doesn't break the run either.
func (Hold) CapFor ¶
CapFor is a day's cap: the held cap while a slowdown holds it, otherwise the planned one.
func (Hold) Moves ¶
Moves reports whether a judged day moves the plan on (review R3.L6d). h is the hold the day was judged under and step what judging it did. A day outside a hold moves the plan when it counted. Under a hold the plan stays on its day, so the cap never jumps several steps when the hold ends: only the healthy day that ends it moves the plan on, and only when the held cap is the day's own planned cap (the healthy days proved it). A hold that stepped back to a lower cap resumes on the day the guard tripped, the one step above the held cap.
type HoldStep ¶
type HoldStep string
HoldStep is what judging a day did to the hold.
const ( HoldNone HoldStep = "" HoldStarted HoldStep = "started" // a guard tripped: the cap holds (or steps back) HoldHealthy HoldStep = "healthy" // a counted day under the hold, more needed HoldEnded HoldStep = "ended" // enough healthy days: the ramp resumes HoldPause HoldStep = "pause" // a guard tripped and the plan pauses )
Hold steps.
type NewPlanInput ¶
type NewPlanInput struct {
ProviderID string `json:"providerId" format:"uuid"`
IP string `json:"ip,omitempty" maxLength:"45"`
WarmupSettings
// TargetVolume is the last day's volume; it defaults to the workspace's
// largest broadcast.
TargetVolume int64 `json:"targetVolume,omitempty" minimum:"0" maximum:"10000000"`
}
NewPlanInput starts a warm-up plan.
type Plan ¶
Plan is a parsed schedule with its progress.
func ParsePlan ¶
func ParsePlan(schedule, progress json.RawMessage) Plan
ParsePlan decodes the schedule and progress columns. Progress rows from before counted days (placeholders without a date) are dropped.
func (Plan) Cap ¶
Cap is the cap the schedule plans for a day. Today's cap (a slowdown's held cap, a pause, the caps per mailbox provider) comes from AllowanceFor.
func (Plan) PlannedCap ¶
PlannedCap is the cap the schedule plans for a day.
type Result ¶
type Result struct {
Day int `json:"day"`
Date string `json:"date"`
Cap int64 `json:"cap"`
// PlannedCap is the schedule's cap when a slowdown held a lower one.
PlannedCap int64 `json:"plannedCap,omitempty"`
Sent int64 `json:"sent"`
// Bounced, Complained and Delivered are the day's counts; complaints
// and deliveries count only mailbox providers that report complaints.
Bounced int64 `json:"bounced,omitempty"`
Complained int64 `json:"complained,omitempty"`
Delivered int64 `json:"delivered,omitempty"`
// Bounce and Complaint are percentages; nil when nothing was measured.
Bounce *float64 `json:"bounce,omitempty"`
Complaint *float64 `json:"complaint,omitempty"`
// Counted: the day moved the plan on. Judged: the guards had enough
// messages to judge it. Short: too little of the cap went out.
Counted bool `json:"counted"`
Judged bool `json:"judged"`
Short bool `json:"short,omitempty"`
// Slowed: a guard tripped on this day (Metric says which).
Slowed bool `json:"slowed,omitempty"`
Metric string `json:"metric,omitempty"`
// Held: a slowdown held this day's cap; Healthy is the healthy day it
// was under the hold (1 of 2, 2 of 2), 0 otherwise.
Held bool `json:"held,omitempty"`
Healthy int `json:"healthy,omitempty"`
}
Result is how one of the workspace's days went: the plan's day on that date, its cap, what went out and how the day was judged (PR-8). A plan day that didn't count appears again on a later date.
type ResumeArgs ¶
type ResumeArgs struct{}
ResumeArgs sends on the shares a warm-up cap held, every five minutes: a share waiting for tomorrow's cap goes on soon after midnight in the workspace's time zone.
func (ResumeArgs) InsertOpts ¶
func (ResumeArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type ResumeWorker ¶
type ResumeWorker struct {
river.WorkerDefaults[ResumeArgs]
S *Service
}
ResumeWorker runs ResumeArgs.
func (*ResumeWorker) Work ¶
func (w *ResumeWorker) Work(ctx context.Context, _ *river.Job[ResumeArgs]) error
Work implements river.Worker.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Now func() time.Time
}
Service serves the warm-up planner.
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, ws *store.Workspace, in NewPlanInput) (WarmupPlanView, error)
Create starts a plan for a provider without one.
func (*Service) DecideCapHold ¶
func (s *Service) DecideCapHold(ctx context.Context, ws *store.Workspace, planID, campaignID string, in WarmupHoldDecision) (WarmupHoldDecisionResult, error)
DecideCapHold waits, moves or cancels a share held at a plan's cap. Waiting and moving resume sending (people who can send); cancelling the held rest stops it (people who can pause sends). A move is vetted first.
func (*Service) Evaluate ¶
Evaluate brings one plan up to date (PR-8): it judges every finished day of the workspace's calendar since the last run, moves the plan on by the days that counted (a day that didn't count repeats), holds the cap after a guard trips until two healthy days in a row without moving the plan meanwhile (the ramp resumes from the held cap, Hold.Moves), raises the Broadcast share on schedule and finishes the plan once every day counted. A paused plan isn't judged: its days wait. Running it twice a day is harmless.
func (*Service) ResumeCapHolds ¶
ResumeCapHolds sends on the shares a warm-up cap held once their provider's new day has started, and the shares a paused plan held once it runs again (unless someone moved or cancelled them). The send loop picks a resumed share up within half a minute.
func (*Service) SetPaused ¶
func (s *Service) SetPaused(ctx context.Context, ws *store.Workspace, id string, paused bool) (WarmupPlanView, error)
SetPaused pauses or resumes a plan. A pause freezes the plan (PR-8): no mail goes to the provider through it, its days aren't judged, and it resumes on the day it stopped.
func (*Service) UpdateSettings ¶
func (s *Service) UpdateSettings(ctx context.Context, ws *store.Workspace, id string, in WarmupSettings) (WarmupPlanView, error)
UpdateSettings changes a plan's length, ordering, guards, mailbox caps and overflow. A new length rebuilds the days ahead from today's cap to the same last volume, so shortening a plan never makes today's cap jump (PR-8); a plan can't get shorter than the days it already counted.
type Verdict ¶
type Verdict struct {
// Counted: the day moved the plan on.
Counted bool
// Judged: the guards had enough messages to judge the day.
Judged bool
// Tripped: a guard tripped (Metric says which).
Tripped bool
Metric string
// Bounce and Complaint are the day's rates in percent, nil when there
// was nothing to measure.
Bounce, Complaint *float64
// Short: too little of the cap went out for the day to count.
Short bool
}
Verdict is how one day was judged.
type WarmupCampaignUse ¶
WarmupCampaignUse is a scheduled campaign's share on a planned day.
type WarmupCandidate ¶
type WarmupCandidate struct {
ProviderID string `json:"providerId"`
Name string `json:"name"`
IPs []string `json:"ips"`
}
WarmupCandidate is a provider that could start a warm-up plan.
type WarmupCapHold ¶
type WarmupCapHold struct {
CampaignID string `json:"campaignId"`
Campaign string `json:"campaign"`
// Held is how many recipients wait; ResumeAt when tomorrow's cap
// starts (the share goes on by itself then); Paused when the plan's
// pause holds it (it goes on when the plan resumes).
Held int64 `json:"held"`
ResumeAt *time.Time `json:"resumeAt,omitempty"`
Paused bool `json:"paused"`
// Decision is "wait" once someone chose to wait.
Decision string `json:"decision,omitempty"`
Alternatives []WarmupHoldAlternative `json:"alternatives"`
}
WarmupCapHold is a campaign's share waiting at the warm-up cap.
type WarmupHoldAlternative ¶
type WarmupHoldAlternative struct {
ProviderID string `json:"providerId"`
Name string `json:"name"`
Short string `json:"short"`
Allowed bool `json:"allowed"`
Checks []state.VetCheck `json:"checks"`
}
WarmupHoldAlternative is a provider the held share could move to, with the checks it was vetted with (state.Vet).
type WarmupHoldDecision ¶
type WarmupHoldDecision struct {
Action string `json:"action" enum:"wait,move,cancel"`
// TargetProviderID is where "move" sends the held share.
TargetProviderID string `json:"targetProviderId,omitempty" format:"uuid"`
}
WarmupHoldDecision is what to do with a share held at the warm-up cap.
type WarmupHoldDecisionResult ¶
type WarmupHoldDecisionResult struct {
Action string `json:"action"`
// Moved is how many recipients moved, Cancelled how many won't get it.
Moved int64 `json:"moved"`
Cancelled int64 `json:"cancelled"`
}
WarmupHoldDecisionResult says what happened.
type WarmupLogEntry ¶
type WarmupLogEntry struct {
At time.Time `json:"at"`
Kind string `json:"kind"`
Title string `json:"title"`
Body string `json:"body"`
}
WarmupLogEntry is one line of the warm-up log.
type WarmupMailboxCap ¶
type WarmupMailboxCap struct {
Mailbox string `json:"mailbox"`
Percent int `json:"percent"`
Cap int64 `json:"cap"`
Sent int64 `json:"sent"`
}
WarmupMailboxCap is today's cap and sends of one mailbox provider.
type WarmupOverview ¶
type WarmupOverview struct {
Plans []WarmupPlanView `json:"plans"`
Candidates []WarmupCandidate `json:"candidates"`
}
WarmupOverview is the warm-up tab.
type WarmupPlanView ¶
type WarmupPlanView struct {
ID string `json:"id"`
ProviderID string `json:"providerId"`
Provider string `json:"provider"`
Short string `json:"short"`
IP string `json:"ip"`
Status string `json:"status" enum:"active,slowed,paused,done"`
StatusDetail string `json:"statusDetail"`
// Day is today's plan day; Counted the days that counted so far, of
// Days; CalendarDays the days since the plan started (today excluded).
Day int `json:"day"`
Days int `json:"days"`
Counted int `json:"counted"`
CalendarDays int `json:"calendarDays"`
// StartedOn is the day the plan began; FinishesOn the earliest day it
// can finish (every day from today counting).
StartedOn time.Time `json:"startedOn"`
FinishesOn time.Time `json:"finishesOn"`
Progress float64 `json:"progress" doc:"Percent of the plan's days counted"`
TodayCap int64 `json:"todayCap"`
SentToday int64 `json:"sentToday"`
// NeedToday is what today needs to count; RepeatsTomorrow is true when
// today can't count any more (nothing scheduled and too little sent).
NeedToday int64 `json:"needToday"`
RepeatsTomorrow bool `json:"repeatsTomorrow"`
// ScheduledToday is how many campaigns use the provider today.
ScheduledToday int `json:"scheduledToday"`
SentTotal int64 `json:"sentTotal"`
// BounceRate and ComplaintRate cover the last seven days; nil when
// nothing was measured (complaints count only mailbox providers that
// report them).
BounceRate *float64 `json:"bounceRate,omitempty"`
ComplaintRate *float64 `json:"complaintRate,omitempty"`
Slowdowns int `json:"slowdowns"`
LastSlowdown *WarmupSlowdown `json:"lastSlowdown,omitempty"`
RateToday float64 `json:"rateToday"`
NextRate *WarmupStep `json:"nextRate,omitempty"`
// Held is the cap a slowdown holds and HealthyStreak the healthy days so far.
Held *int64 `json:"held,omitempty"`
HealthyStreak int `json:"healthyStreak"`
HealthyDays int `json:"healthyDays"`
MinSample int `json:"minSample"`
Rows []WarmupRow `json:"rows"`
Ramp []WarmupRampDay `json:"ramp"`
MailboxCaps []WarmupMailboxCap `json:"mailboxCaps"`
// OverflowTo is the warm provider over-cap mail goes through (the
// largest share of the Broadcasts split that isn't warming up), empty
// when there is none; OverflowToday what went through it today.
OverflowTo string `json:"overflowTo,omitempty"`
OverflowToday int64 `json:"overflowToday"`
// TransactionalOverCap is how many transactional messages went out over
// today's cap (or while the plan was paused) because no warm provider of
// their route could take them: transactional mail never waits, and it
// counts toward the cap (review R3.L6b).
TransactionalOverCap int64 `json:"transactionalOverCap"`
Settings WarmupSettings `json:"settings"`
// Holds are campaigns' shares waiting at today's cap, with choices.
Holds []WarmupCapHold `json:"holds"`
Log []WarmupLogEntry `json:"log"`
CreatedBy string `json:"createdBy"`
}
WarmupPlanView is a warm-up plan with its progress (ProvidersWarmup).
type WarmupRampDay ¶
type WarmupRampDay struct {
Day int `json:"day"`
PlannedCap int64 `json:"plannedCap"`
Sent *int64 `json:"sent,omitempty"`
Slowed bool `json:"slowed"`
Today bool `json:"today"`
}
WarmupRampDay is one day of the volume ramp (the chart).
type WarmupRow ¶
type WarmupRow struct {
Day int `json:"day"`
Date time.Time `json:"date"`
Cap int64 `json:"cap"`
// PlannedCap is the schedule's cap when a slowdown holds a lower one.
PlannedCap int64 `json:"plannedCap,omitempty"`
Sent *int64 `json:"sent,omitempty"`
Bounce *float64 `json:"bounce,omitempty"`
Complaint *float64 `json:"complaint,omitempty"`
Tiers []string `json:"tiers"`
// ShareChange is true on the day the Broadcast share steps up.
Uses []WarmupCampaignUse `json:"uses"`
// Status: counted, not_counted, today, planned.
Status string `json:"status" enum:"counted,not_counted,today,planned"`
// Why a day didn't count: short (under 80% of its cap went out), guard
// (a guard tripped; Metric says which) or held (a healthy day under a
// slowdown's hold: it proves the held cap without moving the plan on).
Reason string `json:"reason,omitempty" enum:"short,guard,held"`
Metric string `json:"metric,omitempty" enum:"bounce,complaint"`
// Judged: the guards had enough messages to judge the day.
Judged bool `json:"judged"`
// Bounced, Complained and Delivered are the day's counts (complaints
// and deliveries at mailbox providers that report complaints), so
// several days add up exactly.
Bounced int64 `json:"bounced"`
Complained int64 `json:"complained"`
Delivered int64 `json:"delivered"`
// Need is how many messages the day needs to count.
Need int64 `json:"need"`
// Held: a slowdown held the day's cap; Healthy is the healthy day it
// was under the hold (1 of HealthyDays…).
Held bool `json:"held"`
Healthy int `json:"healthy,omitempty"`
// Repeat marks a planned day that repeats a day that didn't count.
Repeat bool `json:"repeat"`
// Eligible marks the last day: the provider then becomes a Broadcast
// failover target.
Eligible bool `json:"eligible"`
}
WarmupRow is one date of the plan table: a day that was judged, today, or a planned day (dates ahead assume every day counts).
type WarmupSettings ¶
type WarmupSettings struct {
// Days is the plan's length in counted days.
Days int `json:"days" enum:"14,21,30"`
EngagedFirst bool `json:"engagedFirst"`
GuardBounce float64 `json:"guardBounce" minimum:"0.5" maximum:"10"`
GuardComplaint float64 `json:"guardComplaint" minimum:"0.01" maximum:"1"`
GuardAction string `json:"guardAction" enum:"hold,step_back,pause"`
SpreadMailbox bool `json:"spreadMailbox"`
// Overflow sends what's over today's cap through a warm provider of
// the same route instead of waiting for tomorrow's cap.
Overflow *bool `json:"overflow,omitempty"`
}
WarmupSettings are a plan's editable settings.
type WarmupSlowdown ¶
type WarmupSlowdown struct {
Day int `json:"day"`
Metric string `json:"metric" enum:"bounce,complaint"`
Rate *float64 `json:"rate,omitempty"`
}
WarmupSlowdown summarizes the last slowdown ("day 6, bounces 2.3%").
type WarmupStep ¶
WarmupStep is a planned change ("rises to 4 /s on day 12").