state

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: 8 Imported by: 0

Documentation

Overview

Package state describes what ReputeCast stores about a connected provider in the providers table's JSON columns (capability snapshot, health, pricing, limits, provider-side tracking, where its sending IPs come from) and the display helpers every screen shares (short names, chart colours). It has no database access, so routing, warm-up, ingest and the providers service can all use it.

These types are a contract that Deliverability, Overview, send readiness and the sending engine read: fields keep their JSON names and meanings and are only ever added. Percentages are plain percent values (0.1 means 0.1%), money is US dollars, times are UTC.

Texts people read later (the account's standing, a status page's incident, a tracking detail, an error ReputeCast or the adapter worded) keep their English and, beside it, the message they come from as an i18n.Text (AccountText, SummaryText…): read them with providers.TextIn(english, text, lang). Rows written before the messages were kept read in English.

A provider whose providers.config holds "demo": true is sample data: background jobs never call its API and the sending engine simulates it.

Index

Constants

View Source
const (
	DetailDown           = "Down"
	DetailDownAuth       = "Down · auth failed"
	DetailWebhooksSilent = "Webhooks silent"
	DetailRejecting      = "Rejecting messages"
	DetailMailboxFailing = "Bounce mailbox unreachable"
	DetailQueueFailing   = "Event queue unreachable"
)

The health check's words in providers.status_detail (providers/manage writes them, and rows keep the English).

View Source
const (
	Healthy   = "healthy"
	Degraded  = "degraded"
	Down      = "down"
	Sandbox   = "sandbox"
	WarmingUp = "warming_up"
	Paused    = "paused"
)

Provider statuses (providers.status).

View Source
const (
	// IPsFromProvider: its API lists them (providers.IPReporter); ReputeCast
	// asks when the provider is connected and every day.
	IPsFromProvider = "provider"
	// IPsFromPerson: a person set them, for a provider whose API can't list
	// them.
	IPsFromPerson = "manual"
)

Where a provider's sending IPs come from (IPSource.From).

View Source
const (
	VetAvailable = "available"  // connected, not down or paused, events arriving
	VetBulkTerms = "bulk_terms" // its terms allow Broadcasts
	VetSandbox   = "sandbox"    // the account may send to anyone
	VetDomain    = "domain"     // the sender is verified there
	VetQuota     = "quota"      // what is left of its quota covers the mail
	VetWarm      = "warm"       // not warming up, or today's cap covers the mail
)

Vetting checks, in the order screens list them.

View Source
const (
	VetPass = "pass"
	// VetWarn is possible at a cost a person chooses: a warming IP takes
	// mail its plan didn't count on.
	VetWarn = "warn"
	VetFail = "fail"
	// VetUnknown is what ReputeCast can't tell: a sender on a provider
	// without a domain API, a quota not read yet.
	VetUnknown = "unknown"
)

Check results.

View Source
const MailboxFailAfter = 15 * time.Minute

MailboxFailAfter is how long a bounce mailbox may fail to be read before the provider is Degraded and the team is told: a mail server restarting is no alarm.

View Source
const ReputationFresh = 48 * time.Hour

ReputationFresh is how long a provider-reported reputation is used.

Variables

This section is empty.

Functions

func Available

func Available(p store.Provider) bool

Available reports whether new mail may be routed to the provider.

func Color

func Color(adapter string) string

Color is the sending-provider chart colour key ("ses", "postal", "postmark") from the design system; other adapters share "other".

func DetailIn

func DetailIn(detail string, l i18n.Lang) string

DetailIn is a provider's status detail for a reader: the health check's words in the reader's language, anything else (the account's standing, in the provider's words) as stored. English readers get the stored text.

func Location

func Location(tz string) *time.Location

Location loads a workspace timezone, UTC when unknown.

func SenderVerification

func SenderVerification(raw json.RawMessage) map[string]string

SenderVerification decodes a sender's verification per provider ID (senders.verification).

func Short

func Short(name, adapter string) string

Short is the label used in badges and legends: "SES", "Postal", "Postmark".

func WarmupDay

func WarmupDay(start, now time.Time, loc *time.Location) int

WarmupDay is the day number (1-based) of a warm-up plan that started on start, on the calendar of loc.

Types

type CallRecord

type CallRecord struct {
	At      time.Time `json:"at"`
	Op      string    `json:"op"`
	Status  int       `json:"status,omitempty"`
	Code    string    `json:"code,omitempty"`
	Message string    `json:"message,omitempty"`
	// Text is the message Message comes from when ReputeCast or the adapter
	// worded it (providers.CallError.Text); a provider's own answer has none.
	Text i18n.Text `json:"text,omitzero"`
}

CallRecord is one API call result kept for the "Recent errors" list.

type DownState

type DownState struct {
	Since  time.Time `json:"since"`
	Reason string    `json:"reason"` // outage, auth
	// NotifiedAt is when members were told (once per outage).
	NotifiedAt *time.Time `json:"notifiedAt,omitempty"`
	// ProviderStatus is what the provider's public status page said.
	ProviderStatus *ProviderStatus `json:"providerStatus,omitempty"`
	// RecoveringSince is when calls started succeeding again; the provider
	// is healthy again after ten healthy minutes.
	RecoveringSince *time.Time `json:"recoveringSince,omitempty"`
}

DownState describes an outage or rejected credentials.

type Health

type Health struct {
	Quota *Quota `json:"quota,omitempty"`
	Rate  *Rate  `json:"rate,omitempty"`
	// Account is the account standing as the provider reports it
	// ("Production · no enforcement", "Approved · 10,000 per month plan"),
	// and AccountText the message it comes from.
	Account     string    `json:"account,omitempty"`
	AccountText i18n.Text `json:"accountText,omitzero"`
	// Sandbox is true while the account can only send to verified addresses.
	Sandbox bool `json:"sandbox,omitempty"`
	// ConsecutiveFailures counts failed health checks in a row.
	ConsecutiveFailures int         `json:"consecutiveFailures,omitempty"`
	LastSuccessAt       *time.Time  `json:"lastSuccessAt,omitempty"`
	LastSuccessOp       string      `json:"lastSuccessOp,omitempty"`
	LastError           *CallRecord `json:"lastError,omitempty"`
	// RecentErrors are the last API failures, newest first (at most 10).
	RecentErrors []CallRecord `json:"recentErrors,omitempty"`
	// Down is set while the provider is down (outage or rejected credentials).
	Down *DownState `json:"down,omitempty"`
	// Webhooks is set once the health job has checked webhook freshness.
	Webhooks *WebhookState `json:"webhooks,omitempty"`
	// Version is the provider software version when it reports one
	// (Postal's webhook User-Agent).
	Version string `json:"version,omitempty"`
	// VDM is true when Amazon SES's Virtual Deliverability Manager is on.
	VDM bool `json:"vdm,omitempty"`
	// Reputation is the bounce and complaint rate the provider itself
	// reports for the account, when its API offers one. Screens prefer it
	// to ReputeCast's own count while it is fresh (see ReputationOf).
	Reputation *Reputation `json:"reputation,omitempty"`
	// LastRejection is the last message the provider refused for good, in
	// its own code and words (manage.RecordSend).
	LastRejection *CallRecord `json:"lastRejection,omitempty"`
	// Rejecting is set while the provider refuses an unusual share of the
	// messages handed to it (PR-7, the health job).
	Rejecting *RejectState `json:"rejecting,omitempty"`
	// BounceMailbox is the last read of an SMTP provider's bounce mailbox
	// (PR-10): when reading fails, bounces from that server go unseen.
	BounceMailbox *MailboxState `json:"bounceMailbox,omitempty"`
	// EventQueue is the last poll of the SQS queue an SES connection's
	// events arrive in (PR-4).
	EventQueue *MailboxState `json:"eventQueue,omitempty"`
}

Health is the snapshot the health job writes into providers.health.

func HealthOf

func HealthOf(p store.Provider) Health

HealthOf decodes a provider's health snapshot.

func (Health) MailboxFailing

func (h Health) MailboxFailing(now time.Time) bool

MailboxFailing reports whether a bounce mailbox has failed long enough to be raised.

type IPSource

type IPSource struct {
	// From is IPsFromProvider, IPsFromPerson or "" (nobody yet: what
	// connecting set).
	From string `json:"from,omitempty"`
	// CheckedAt is the provider's last answer.
	CheckedAt *time.Time `json:"checkedAt,omitempty"`
	// Error is the last check's failure, while the IPs stay what the last
	// answer said; ErrorText is the message it comes from, when the
	// adapter worded it (providers.CallError.Text).
	Error     string     `json:"error,omitempty"`
	ErrorText i18n.Text  `json:"errorText,omitzero"`
	ErrorAt   *time.Time `json:"errorAt,omitempty"`
	// SetBy is the member who set the IPs by hand (nil for an API key or an
	// agent), SetByName the name of whoever did, as it was then.
	SetBy     *uuid.UUID `json:"setBy,omitempty"`
	SetByName string     `json:"setByName,omitempty"`
	SetAt     *time.Time `json:"setAt,omitempty"`
}

IPSource is where a provider's sending IPs (providers.ip_mode and ips) come from (providers.ip_source).

func IPSourceOf

func IPSourceOf(p store.Provider) IPSource

IPSourceOf decodes where a provider's sending IPs come from.

type Limit

type Limit struct {
	// Limit is the line the bar is drawn against, in percent.
	Limit float64 `json:"limit"`
	// Review and Pause are the provider's own enforcement levels (SES).
	Review float64 `json:"review,omitempty"`
	Pause  float64 `json:"pause,omitempty"`
	// Label names whose limit it is ("SES", "Postmark", "warm-up guard").
	Label string `json:"label,omitempty"`
}

Limit is a rate limit shown against a provider's bounce or complaint rate.

type Limits

type Limits struct {
	Bounce    Limit `json:"bounce"`
	Complaint Limit `json:"complaint"`
}

Limits are a provider's bounce and complaint limits.

func LimitsOf

func LimitsOf(p store.Provider) Limits

LimitsOf decodes a provider's limits with sensible defaults.

type Load

type Load struct {
	// Broadcast is true for Broadcasts, to which bulk terms apply.
	Broadcast bool
	// Messages is how many messages would move.
	Messages int64
	// Sender is the sender's verification per provider ID
	// (senders.verification); nil when the mail has no stored sender.
	Sender map[string]string
	// Warmup is the target's warm-up today, nil when no plan is running.
	Warmup *WarmupToday
}

Load is what would move to a target.

type MailboxState

type MailboxState struct {
	LastPollAt time.Time  `json:"lastPollAt"`
	LastOKAt   *time.Time `json:"lastOkAt,omitempty"`
	// Error is the last failure, as the mail server or the network said
	// it; FailingSince is when reading started to fail.
	Error        string     `json:"error,omitempty"`
	FailingSince *time.Time `json:"failingSince,omitempty"`
	// Reported is set once the failure was raised (incident, notification).
	Reported bool `json:"reported,omitempty"`
}

MailboxState is how reading a bounce mailbox goes.

type NextTier

type NextTier struct {
	Adds  int64   `json:"adds"`
	Price float64 `json:"price"`
}

NextTier is a provider plan's next step.

type Pricing

type Pricing struct {
	Model string `json:"model"` // metered, plan, self_hosted
	// Per1000 is the metered price per 1,000 emails.
	Per1000 float64 `json:"per1000,omitempty"`
	// Monthly is the plan or server price per month.
	Monthly float64 `json:"monthly,omitempty"`
	// Source explains the per-1,000 figure for metered pricing ("AWS
	// pricing"); SourceText is its message, for readers in other languages.
	Source     string    `json:"source,omitempty"`
	SourceText i18n.Text `json:"sourceText,omitzero"`
	// NextTier is the next plan step ("adds 50,000 for $115").
	NextTier *NextTier `json:"nextTier,omitempty"`
}

Pricing is how a provider is paid for.

func PricingOf

func PricingOf(p store.Provider) Pricing

PricingOf decodes a provider's pricing.

type ProviderStatus

type ProviderStatus struct {
	Incident  bool      `json:"incident"`
	Summary   string    `json:"summary,omitempty"`
	CheckedAt time.Time `json:"checkedAt"`
	// SummaryText is the message Summary comes from.
	SummaryText i18n.Text `json:"summaryText,omitzero"`
}

ProviderStatus is a public status page reading.

type Quota

type Quota struct {
	// Kind is rolling_24h (SES), monthly_plan (Postmark) or warmup_daily
	// (today's cap of a warm-up plan).
	Kind string `json:"kind"`
	// Max is the allowance in messages; Used is what was sent against it.
	Max  int64 `json:"max"`
	Used int64 `json:"used"`
}

Quota is the provider's sending allowance.

type Rate

type Rate struct {
	Max       float64 `json:"max,omitempty"`
	Now       float64 `json:"now"`
	PeakToday float64 `json:"peakToday"`
	// Label names where the limit comes from ("ramp limit").
	Label string `json:"label,omitempty"`
}

Rate is the send rate in messages per second: the limit (0 when the provider publishes none) and what was used.

type RejectState

type RejectState struct {
	Since    time.Time `json:"since"`
	Rejected int64     `json:"rejected"`
	Total    int64     `json:"total"`
	Code     string    `json:"code,omitempty"`
	Message  string    `json:"message,omitempty"`
}

RejectState is a run of refused messages: since when, how many of how many in the health job's window, and the provider's last answer.

type Reputation

type Reputation struct {
	// Bounce and Complaint are percentages (0.2 means 0.2%).
	Bounce    float64 `json:"bounce"`
	Complaint float64 `json:"complaint"`
	// Window is the period the provider measured ("7 d").
	Window    string    `json:"window,omitempty"`
	CheckedAt time.Time `json:"checkedAt"`
}

Reputation is a provider-reported bounce and complaint rate.

func ReputationOf

func ReputationOf(h Health, now time.Time) *Reputation

ReputationOf returns the provider-reported reputation when it is recent enough to show instead of ReputeCast's own 7-day count.

type Snapshot

type Snapshot struct {
	providers.Capabilities
	// BroadcastStream is true when the account has a stream on which its
	// terms allow bulk mail (Postmark Broadcast stream).
	BroadcastStream bool `json:"broadcastStream,omitempty"`
}

Snapshot is the capability snapshot stored when a provider is connected: the adapter's capabilities plus what this connection adds.

func Caps

func Caps(p store.Provider) Snapshot

Caps decodes a provider's capability snapshot, falling back to the adapter's declared capabilities.

func (Snapshot) BulkAllowed

func (s Snapshot) BulkAllowed() bool

BulkAllowed reports whether Broadcasts may go through the provider under its terms.

type Tracking

type Tracking struct {
	// OpenPixel and LinkRewrite are true when the provider adds its own open
	// pixel or rewrites links (double tracking with ReputeCast's).
	OpenPixel   bool `json:"openPixel"`
	LinkRewrite bool `json:"linkRewrite"`
	// Detail is what was found ("Open tracking on the default configuration
	// set"); Scope is where (a configuration set, a message stream).
	Detail string `json:"detail,omitempty"`
	Scope  string `json:"scope,omitempty"`
	// DetailText and ScopeText are the messages Detail and Scope come from.
	DetailText i18n.Text `json:"detailText,omitzero"`
	ScopeText  i18n.Text `json:"scopeText,omitzero"`
	// Mode is "reputecast" (ours, the default) or "provider" when a person
	// chose to keep the provider's tracking and ignore ReputeCast's.
	Mode      string     `json:"mode,omitempty"`
	CheckedAt *time.Time `json:"checkedAt,omitempty"`
	Error     string     `json:"error,omitempty"`
}

Tracking is the provider-side tracking found by the tracking check.

func TrackingOf

func TrackingOf(p store.Provider) Tracking

TrackingOf decodes a provider's tracking state.

type VetCheck

type VetCheck struct {
	Key    string `json:"key"`
	Result string `json:"result"`
	// Left and Need are what a quota or warm-up check compares: what the
	// provider can still take and what would move.
	Left *int64 `json:"left,omitempty"`
	Need *int64 `json:"need,omitempty"`
	// Detail qualifies the result: the provider's status, the sender's
	// verification there ("pending", "not_set_up"), the quota's kind.
	Detail string `json:"detail,omitempty"`
	// Text is the finding in the reader's language (Vetting.In), empty
	// for a passed check.
	Text string `json:"text,omitempty"`
}

VetCheck is one finding about a target.

func (VetCheck) In

func (c VetCheck) In(l i18n.Lang, provider string) string

In is the check's sentence about a provider for a reader ("" when it passed).

func (VetCheck) Keep

func (c VetCheck) Keep(provider string) i18n.Text

Keep is the check's sentence about a provider, kept as a message so a stored decision reads in each reader's language. Passed checks have none.

type Vetting

type Vetting struct {
	Checks []VetCheck `json:"checks"`
}

Vetting is what Vet found about one target.

func Vet

func Vet(p store.Provider, l Load) Vetting

Vet checks whether a provider can take a load.

func (Vetting) Allowed

func (v Vetting) Allowed() bool

Allowed reports whether a person may move mail there: no check failed.

func (Vetting) Automatic

func (v Vetting) Automatic(acceptWarming bool) bool

Automatic reports whether mail may move there without asking anyone: every check passed, or only the warm-up warned and the failover policy accepts warming providers.

func (Vetting) Failed

func (v Vetting) Failed() (VetCheck, bool)

Failed is the first failed check.

func (Vetting) In

func (v Vetting) In(l i18n.Lang, provider string) Vetting

In returns the checks with their sentences about the provider, in a reader's language.

func (Vetting) Warming

func (v Vetting) Warming() bool

Warming reports whether the target is warming up.

type WarmupToday

type WarmupToday struct {
	Cap    int64
	Sent   int64
	Paused bool
}

WarmupToday is a warming provider's allowance today.

type WebhookCheck

type WebhookCheck struct {
	Key    string     `json:"key"` // api, registered, endpoint, provider_log
	OK     *bool      `json:"ok,omitempty"`
	At     *time.Time `json:"at,omitempty"`
	Detail string     `json:"detail,omitempty"`
	ID     string     `json:"id,omitempty"`
	URL    string     `json:"url,omitempty"`
	Count  *int64     `json:"count,omitempty"`
	Queued *int64     `json:"queued,omitempty"`
	// DetailText is the message Detail comes from.
	DetailText i18n.Text `json:"detailText,omitzero"`
}

WebhookCheck is one finding of the webhooks-silent diagnosis.

type WebhookState

type WebhookState struct {
	// SilentSince is the last event before a silence of six hours or more.
	SilentSince *time.Time     `json:"silentSince,omitempty"`
	NotifiedAt  *time.Time     `json:"notifiedAt,omitempty"`
	Checks      []WebhookCheck `json:"checks,omitempty"`
	// Causes are likely causes, most likely first (worker_stuck, firewall,
	// secret_rotated, webhook_removed, endpoint_unreachable).
	Causes    []string   `json:"causes,omitempty"`
	CheckedAt *time.Time `json:"checkedAt,omitempty"`
}

WebhookState is the webhook freshness of a provider.

Jump to

Keyboard shortcuts

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