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
- func Available(p store.Provider) bool
- func Color(adapter string) string
- func DetailIn(detail string, l i18n.Lang) string
- func Location(tz string) *time.Location
- func SenderVerification(raw json.RawMessage) map[string]string
- func Short(name, adapter string) string
- func WarmupDay(start, now time.Time, loc *time.Location) int
- type CallRecord
- type DownState
- type Health
- type IPSource
- type Limit
- type Limits
- type Load
- type MailboxState
- type NextTier
- type Pricing
- type ProviderStatus
- type Quota
- type Rate
- type RejectState
- type Reputation
- type Snapshot
- type Tracking
- type VetCheck
- type Vetting
- type WarmupToday
- type WebhookCheck
- type WebhookState
Constants ¶
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).
const ( Healthy = "healthy" Degraded = "degraded" Down = "down" Sandbox = "sandbox" WarmingUp = "warming_up" Paused = "paused" )
Provider statuses (providers.status).
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).
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.
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.
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.
const ReputationFresh = 48 * time.Hour
ReputationFresh is how long a provider-reported reputation is used.
Variables ¶
This section is empty.
Functions ¶
func Color ¶
Color is the sending-provider chart colour key ("ses", "postal", "postmark") from the design system; other adapters share "other".
func DetailIn ¶
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 SenderVerification ¶
func SenderVerification(raw json.RawMessage) map[string]string
SenderVerification decodes a sender's verification per provider ID (senders.verification).
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.
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 ¶
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 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 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.
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 ¶
Caps decodes a provider's capability snapshot, falling back to the adapter's declared capabilities.
func (Snapshot) BulkAllowed ¶
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 ¶
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.
type Vetting ¶
type Vetting struct {
Checks []VetCheck `json:"checks"`
}
Vetting is what Vet found about one target.
func (Vetting) Automatic ¶
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.
type WarmupToday ¶
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.