state

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: 5 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) 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.

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 (
	Healthy   = "healthy"
	Degraded  = "degraded"
	Down      = "down"
	Sandbox   = "sandbox"
	WarmingUp = "warming_up"
	Paused    = "paused"
)

Provider statuses (providers.status).

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 Location

func Location(tz string) *time.Location

Location loads a workspace timezone, UTC when unknown.

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"`
}

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").
	Account string `json:"account,omitempty"`
	// 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"`
}

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.

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 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").
	Source string `json:"source,omitempty"`
	// 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"`
}

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 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"`
	// 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 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"`
}

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