warmup

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

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

This section is empty.

Variables

View Source
var Tiers = []string{"active", "cooling", "at_risk", "sunset"}

Engagement tiers in order of engagement.

Functions

func RateFor

func RateFor(cap int64) float64

RateFor is the default rate for a daily cap: spread over about an hour of sending at the start, never under 1 /s.

func Register

func Register(h huma.API, s *Service)

Register adds the warm-up operations.

Types

type Allowance

type Allowance struct {
	Cap    int64
	Sent   int64
	Rate   float64
	Tiers  []string
	Spread bool
	Paused bool
	Day    int
	Days   int
}

Allowance is what a warming provider may send today. The sending pipeline sends no more than Cap-Sent messages at Rate per second, to the listed engagement tiers, spread across mailbox providers when Spread.

func AllowanceFor

func AllowanceFor(ctx context.Context, q *store.Queries, providerID uuid.UUID, now time.Time, loc *time.Location) (Allowance, bool, error)

AllowanceFor returns a provider's warm-up allowance; ok is false when the provider has no running plan.

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.

func (DailyArgs) Kind

func (DailyArgs) Kind() string

Kind implements river.JobArgs.

type DailyWorker

type DailyWorker struct {
	river.WorkerDefaults[DailyArgs]
	S   *Service
	Log *slog.Logger
	// Skip leaves a provider alone (sample data).
	Skip func(store.Provider) bool
}

func (*DailyWorker) Work

func (w *DailyWorker) Work(ctx context.Context, _ *river.Job[DailyArgs]) error

Work implements river.Worker.

type Day

type Day struct {
	Day    int     `json:"day"`
	Volume int64   `json:"volume"`
	Rate   float64 `json:"rate,omitempty"`
	// Share is the provider's Broadcast share in percent from this day.
	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

func Ramp(n int, first, last int64) []Day

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%.

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

type Plan struct {
	Schedule []Day
	Progress []Result
}

Plan is a parsed schedule with its progress.

func ParsePlan

func ParsePlan(schedule, progress json.RawMessage) Plan

ParsePlan decodes the schedule and progress columns.

func (Plan) Cap

func (p Plan) Cap(d int) int64

Cap is a day's volume cap: the planned volume, or the cap a slowdown set for it (the warm-up job records it when the guard trips).

func (Plan) PlannedCap

func (p Plan) PlannedCap(d int) int64

PlannedCap is the cap the schedule planned for a day.

func (Plan) Rate

func (p Plan) Rate(d int) float64

Rate is a day's rate limit per second.

func (Plan) Result

func (p Plan) Result(d int) (Result, bool)

Result returns the recorded result of a day.

func (Plan) Share

func (p Plan) Share(d int) int

Share is the provider's Broadcast share on a day, in percent.

func (Plan) TiersOn

func (p Plan) TiersOn(d int) []string

TiersOn is the audience of a day.

type Result

type Result struct {
	Day       int     `json:"day"`
	Date      string  `json:"date"`
	Cap       int64   `json:"cap"`
	Sent      int64   `json:"sent"`
	Bounce    float64 `json:"bounce"`
	Complaint float64 `json:"complaint"`
	// Slowed: a guard tripped on this day.
	Slowed bool `json:"slowed,omitempty"`
	// Held: this day's cap was held at the previous day's level.
	Held bool `json:"held,omitempty"`
}

Result is what happened on a finished day.

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

Create starts a plan for a provider without one.

func (*Service) Evaluate

func (s *Service) Evaluate(ctx context.Context, planID uuid.UUID) error

Evaluate brings one plan up to date. Running it twice a day is harmless.

func (*Service) Overview

func (s *Service) Overview(ctx context.Context, ws *store.Workspace) (WarmupOverview, error)

Overview returns every plan of the workspace, current plans first.

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.

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 and guards. A new length rebuilds the schedule from the same first and last volumes; days already sent keep their results.

type WarmupCampaignUse

type WarmupCampaignUse struct {
	Name  string `json:"name"`
	Count int64  `json:"count"`
}

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 WarmupDay

type WarmupDay struct {
	Day        int       `json:"day"`
	Date       time.Time `json:"date"`
	Cap        int64     `json:"cap"`
	PlannedCap int64     `json:"plannedCap"`
	Held       bool      `json:"held"`
	Sent       *int64    `json:"sent,omitempty"`
	Bounce     *float64  `json:"bounce,omitempty"`
	Complaint  *float64  `json:"complaint,omitempty"`
	Tiers      []string  `json:"tiers"`
	Share      int       `json:"share"`
	// ShareChange is true on the day the Broadcast share steps up.
	ShareChange bool                `json:"shareChange"`
	Uses        []WarmupCampaignUse `json:"uses"`
	// Status: done, slowdown, resumed, today, planned.
	Status string `json:"status" enum:"done,slowdown,resumed,today,planned"`
	// Eligible marks the day the provider becomes a Broadcast failover target.
	Eligible bool `json:"eligible"`
}

WarmupDay is one day of the ramp.

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 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           int              `json:"day"`
	Days          int              `json:"days"`
	StartDate     time.Time        `json:"startDate"`
	EndDate       time.Time        `json:"endDate"`
	Progress      float64          `json:"progress" doc:"Percent of the plan's days"`
	TodayCap      int64            `json:"todayCap"`
	SentToday     int64            `json:"sentToday"`
	SentTotal     int64            `json:"sentTotal"`
	PlannedToDate int64            `json:"plannedToDate"`
	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"`
	Schedule      []WarmupDay      `json:"schedule"`
	Settings      WarmupSettings   `json:"settings"`
	Log           []WarmupLogEntry `json:"log"`
	CreatedBy     string           `json:"createdBy"`
}

WarmupPlanView is a warm-up plan with its progress.

type WarmupSettings

type WarmupSettings struct {
	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"`
}

WarmupSettings are a plan's editable settings.

type WarmupSlowdown

type WarmupSlowdown struct {
	Day    int     `json:"day"`
	Bounce float64 `json:"bounce"`
}

WarmupSlowdown summarizes the last slowdown ("day 6 held, bounces 2.3%").

type WarmupStep

type WarmupStep struct {
	Day   int     `json:"day"`
	Value float64 `json:"value"`
}

WarmupStep is a planned change ("rises to 4 /s on day 12").

Jump to

Keyboard shortcuts

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