domains

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

Documentation

Overview

Package domains implements sending domains and sender identities (spec 7.13 Settings › Senders, and the domain step of 7.2): the DNS records each sending provider needs (through the provider's domain API when it has one), live verification with internal/dnscheck, the authentication summary per domain, verification per sender and sending provider, the default sender of each stream, custom link-tracking domains, adding records through the Cloudflare API, and a periodic re-verification job.

Index

Constants

View Source
const (
	PurposeDKIM         = "dkim"
	PurposeReturnPath   = "return_path"
	PurposeSPF          = "spf"
	PurposeDMARC        = "dmarc"
	PurposeVerification = "verification"
)

Record purposes.

View Source
const (
	StatusVerified = "verified"
	StatusPending  = "pending"
	StatusWrong    = "wrong_value"
	StatusMissing  = "missing"
	StatusError    = "error"
)

Record statuses.

View Source
const CheckEvery = 30 * time.Minute

CheckEvery is how often the job re-verifies every sending domain ("DNS checked every 30 minutes").

Variables

View Source
var ErrCloudflareToken = errors.New("Cloudflare rejected the API token")

ErrCloudflareToken means Cloudflare refused the token.

Functions

func DNSHostName

func DNSHostName(ns []string) string

DNSHostName names the DNS provider of a set of nameservers.

func EncodeRecords

func EncodeRecords(recs []Record) json.RawMessage

EncodeRecords writes sending_domains.dns_records.

func HostOf

func HostOf(rawURL string) string

HostOf returns the lower-case host name of a URL ("" when it has none).

func MergeSPF

func MergeSPF(current string, mechs []string) string

MergeSPF adds the mechanisms a provider needs to the domain's current SPF record, before its "all" (or redirect) term, keeping everything else. Without a current record it proposes "v=spf1 <mechanisms> -all".

func NormalizeDomain

func NormalizeDomain(field, raw string) (string, error)

NormalizeDomain lowercases a domain name, converts it to ASCII (IDNA) and checks it is a host name.

func Register

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

Register adds the senders and domains operations.

func SPFHas

func SPFHas(record, mech string) bool

SPFHas reports whether an SPF record contains a mechanism.

func SPFMechanisms

func SPFMechanisms(record string) []string

SPFMechanisms returns the mechanisms of an SPF record that authorize senders (include, a, mx, ip4, ip6, exists), without qualifiers.

func SortRecords

func SortRecords(recs []Record, domain string, providerOrder []string)

SortRecords orders records by provider (in the given order, domain-wide records last) and then by purpose.

func StreamName

func StreamName(s string) string

StreamName is the display name of a stream.

func SuggestDMARC

func SuggestDMARC(rua string) string

SuggestDMARC is the policy ReputeCast proposes for a domain without one: quarantine, strict DKIM alignment, relaxed SPF alignment, aggregate reports to HostRepute when it is connected.

Types

type AuthDetail

type AuthDetail struct {
	SPFStatus string `json:"spf_status,omitempty"`
	// SPFAll is the domain's final "all" term ("-all", "~all").
	SPFAll      string `json:"spf_all,omitempty"`
	SPFRecord   string `json:"spf_record,omitempty"`
	DMARCStatus string `json:"dmarc_status,omitempty"`
	DMARCPolicy string `json:"dmarc_policy,omitempty"`
	DMARCRecord string `json:"dmarc_record,omitempty"`
	// DMARCInherited is true when the policy comes from the organizational
	// domain (acme.io for news.acme.io).
	DMARCInherited bool   `json:"dmarc_inherited,omitempty"`
	BIMIStatus     string `json:"bimi_status,omitempty"`
	// MailFrom lists the custom MAIL FROM (return-path) hosts with their
	// alignment.
	MailFrom []MailFromHost `json:"mail_from,omitempty"`
}

AuthDetail is sending_domains.auth_detail: what the last authentication check found, beyond the one-word summary in auth_summary.

type CheckArgs

type CheckArgs struct{}

CheckArgs is the periodic DNS re-verification of sending domains: every domain is checked again every 30 minutes, so a change shows up in Send Readiness within the hour.

func (CheckArgs) InsertOpts

func (CheckArgs) InsertOpts() river.InsertOpts

InsertOpts keeps one sweep at a time.

func (CheckArgs) Kind

func (CheckArgs) Kind() string

Kind implements river.JobArgs.

type CheckWorker

type CheckWorker struct {
	river.WorkerDefaults[CheckArgs]
	S *Service
}

CheckWorker re-verifies the domains whose last check is older than CheckEvery, at most 200 per run.

func (*CheckWorker) Timeout

func (w *CheckWorker) Timeout(*river.Job[CheckArgs]) time.Duration

Timeout bounds one sweep.

func (*CheckWorker) Work

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

Work implements river.Worker.

type Cloudflare

type Cloudflare struct {
	// BaseURL is the API root (tests point it at a fake server).
	BaseURL string
	HTTP    *http.Client
}

Cloudflare adds a domain's missing records through the Cloudflare API ("Add all records via Cloudflare API"). The API token is used for one request and never stored.

func (*Cloudflare) Apply

func (c *Cloudflare) Apply(ctx context.Context, token, domain string, recs []Record) (CloudflareResult, error)

Apply creates or updates every record that isn't verified yet. The sending domain's SPF record is updated in place (two SPF records would break SPF); an existing DMARC record is left alone.

type CloudflareInput

type CloudflareInput struct {
	Token string `` /* 146-byte string literal not displayed */
}

CloudflareInput adds records through the Cloudflare API.

type CloudflareResult

type CloudflareResult struct {
	Zone    string   `json:"zone"`
	Created []string `json:"created"`
	Updated []string `json:"updated"`
	Skipped []string `json:"skipped"`
	Failed  []string `json:"failed"`
}

CloudflareResult is what the API call changed.

type DomainInput

type DomainInput struct {
	Domain string `json:"domain" minLength:"3" maxLength:"253" doc:"The domain senders use, e.g. news.acme.io"`
	Note   string `json:"note,omitempty" maxLength:"120" doc:"What it is for, e.g. primary sending domain"`
}

DomainInput adds a sending domain.

type MailFromHost

type MailFromHost struct {
	Host   string `json:"host"`
	Status string `json:"status"` // aligned, misaligned, missing…
}

MailFromHost is one custom return-path domain.

type ProviderSetupNote

type ProviderSetupNote struct {
	ProviderID string `json:"providerId"`
	Provider   string `json:"provider"`
	Text       string `json:"text"`
}

ProviderSetupNote explains, for a provider whose records ReputeCast can't fetch, what the person does in the provider's own dashboard.

type Record

type Record struct {
	ProviderID string `json:"provider_id,omitempty"`
	// Purpose is dkim, return_path, spf, dmarc or verification.
	Purpose string `json:"purpose"`
	Type    string `json:"type"` // CNAME, TXT, MX
	Name    string `json:"name"`
	Value   string `json:"value"`
	// Status is the live DNS check: pending (not checked yet), verified,
	// wrong_value, missing or error.
	Status string `json:"status,omitempty"`
	// Found is what DNS answered when it differs from Value (for DMARC:
	// the published policy, at FoundName when inherited).
	Found     string `json:"found,omitempty"`
	FoundName string `json:"found_name,omitempty"`
	// TTL is how long resolvers may still serve the found TXT value, in
	// seconds, while it differs from Value (0 when unknown).
	TTL uint32 `json:"ttl,omitempty"`
	// ProviderStatus is the provider's own verdict when its API reports one.
	ProviderStatus string `json:"provider_status,omitempty"`
	// Source says who asked for the record: "provider" (its domain API) or
	// "reputecast" (DMARC, the merged SPF record, manual-DNS providers).
	Source string `json:"source,omitempty"`
	// Mechanisms are the SPF terms a provider needs on the sending domain
	// itself (purpose spf, Name = the domain): Value is the domain's current
	// SPF record with them merged in.
	Mechanisms []string   `json:"mechanisms,omitempty"`
	CheckedAt  *time.Time `json:"checked_at,omitempty"`
}

Record is one DNS record a sending domain needs, stored in sending_domains.dns_records. ProviderID names the sending provider that needs it; it is empty for records every provider relies on (DMARC).

The JSON shape is shared: Deliverability (dnscheck requirements) reads provider_id, purpose, type, name and value, and the route tester reads the DKIM selectors. Fields are only ever added.

func DecodeRecords

func DecodeRecords(raw json.RawMessage) []Record

DecodeRecords reads sending_domains.dns_records.

func RemoveProviderRecords

func RemoveProviderRecords(recs []Record, providerID string) []Record

RemoveProviderRecords drops a provider's records (it was disconnected).

func ReplaceProviderRecords

func ReplaceProviderRecords(recs []Record, providerID string, fresh []Record) []Record

ReplaceProviderRecords swaps a provider's records for fresh ones, keeping the last check of records that didn't change.

type SenderDefaults

type SenderDefaults struct {
	// DefaultSenderID is the Broadcasts default ("Default From for new campaigns").
	DefaultSenderID    string `json:"defaultSenderId"`
	AutomationSenderID string `json:"automationSenderId"`
	SystemSenderID     string `json:"systemSenderId"`
	// ReplyHandling is "forward": replies go to ReplyTo, or to each
	// sender's own reply-to address when ReplyTo is empty. (ReputeCast
	// doesn't receive mail, so there is no reply inbox.)
	ReplyHandling string `json:"replyHandling" enum:"forward"`
	ReplyTo       string `json:"replyTo"`
	FooterAddress string `json:"footerAddress"`
	// TrackingDomain is the default link tracking domain ("" = the
	// provider's default, i.e. ReputeCast's public URL).
	TrackingDomain  string                 `json:"trackingDomain"`
	TrackingOptions []SenderTrackingOption `json:"trackingOptions"`
	ReplyOptions    []string               `json:"replyOptions"`
}

SenderDefaults are the "Defaults" card of Settings › Senders.

type SenderDefaultsInput

type SenderDefaultsInput struct {
	DefaultSenderID string `json:"defaultSenderId,omitempty" doc:"Default From for new campaigns (the Broadcasts default)"`
	ReplyHandling   string `json:"replyHandling" enum:"forward"`
	// ReplyTo is where replies go; empty keeps each sender's own reply-to.
	ReplyTo        string `json:"replyTo,omitempty" maxLength:"254"`
	FooterAddress  string `json:"footerAddress" maxLength:"300"`
	TrackingDomain string `json:"trackingDomain,omitempty" maxLength:"253" doc:"Empty for the provider default"`
}

SenderDefaultsInput saves the "Defaults" card.

type SenderDomainCell

type SenderDomainCell struct {
	Text string `json:"text"`
	Tone string `json:"tone" enum:"ok,warn,bad,neutral"`
}

SenderDomainCell is one status cell of the domains table.

type SenderIdentity

type SenderIdentity struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	ReplyTo  string `json:"replyTo"`
	Note     string `json:"note"`
	DomainID string `json:"domainId"`
	Domain   string `json:"domain"`
	// DefaultFor lists the streams this sender is the default From of.
	DefaultFor   []string             `json:"defaultFor"`
	Verification []SenderVerification `json:"verification"`
	// Pending is true while a provider that sends as this address still
	// waits for the domain's DNS records ("Verify").
	Pending bool `json:"pending"`
}

SenderIdentity is one row of "Sender identities".

type SenderInput

type SenderInput struct {
	Name    string `json:"name" minLength:"1" maxLength:"120"`
	Email   string `json:"email,omitempty" maxLength:"254" doc:"Required when creating; the address can't change later"`
	ReplyTo string `json:"replyTo,omitempty" maxLength:"254"`
	Note    string `json:"note,omitempty" maxLength:"120" doc:"Shown when the sender is no stream's default, e.g. personal sends"`
	// DefaultFor makes the sender the default From of these streams.
	DefaultFor []string `json:"defaultFor,omitempty" enum:"broadcast,automation,system"`
	// NotUsedWith lists providers that must never send as this address.
	NotUsedWith []string `json:"notUsedWith,omitempty"`
}

SenderInput creates or changes a sender identity.

type SenderProviderColumn

type SenderProviderColumn struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Short   string `json:"short"`
	Adapter string `json:"adapter"`
}

SenderProviderColumn is a connected sending provider.

type SenderTrackingOption

type SenderTrackingOption struct {
	Domain   string `json:"domain"`
	Verified bool   `json:"verified"`
}

SenderTrackingOption is a tracking domain that can be the default.

type SenderVerification

type SenderVerification struct {
	ProviderID string `json:"providerId"`
	Status     string `json:"status" enum:"verified,pending,failed,not_set_up,not_used"`
	// Text is the badge: "Verified", "Pending · acme.io DKIM", "Not set up", "Not used".
	Text string `json:"text"`
}

SenderVerification is one sending-provider column of a sender row.

type SendersOverview

type SendersOverview struct {
	Senders   []SenderIdentity       `json:"senders"`
	Domains   []SendingDomainRow     `json:"domains"`
	Providers []SenderProviderColumn `json:"providers"`
	Defaults  SenderDefaults         `json:"defaults"`
	CanManage bool                   `json:"canManage"`
	// Helpers names who can manage domains and senders when the caller can't.
	Helpers []string `json:"helpers"`
}

SendersOverview is Settings › Senders.

type SendingDomainCloudflareResult

type SendingDomainCloudflareResult struct {
	Result CloudflareResult    `json:"result"`
	Domain SendingDomainDetail `json:"domain"`
}

SendingDomainCloudflareResult is what Cloudflare changed and the fresh check.

type SendingDomainCounts

type SendingDomainCounts struct {
	Verified int `json:"verified"`
	Pending  int `json:"pending"`
	Missing  int `json:"missing"`
	Total    int `json:"total"`
}

SendingDomainCounts summarize the records ("5 of 7 verified").

type SendingDomainCreated

type SendingDomainCreated struct {
	Domain SendingDomainDetail `json:"domain"`
	Notes  []ProviderSetupNote `json:"notes"`
}

SendingDomainCreated is a new domain with what to do in providers' dashboards that ReputeCast couldn't set up.

type SendingDomainDetail

type SendingDomainDetail struct {
	ID          string                 `json:"id"`
	Domain      string                 `json:"domain"`
	Note        string                 `json:"note"`
	Status      string                 `json:"status" enum:"pending,verified,partial,failed"`
	DNSHost     string                 `json:"dnsHost"`
	Nameservers []string               `json:"nameservers"`
	Cloudflare  bool                   `json:"cloudflare"`
	Records     []SendingDomainRecord  `json:"records"`
	Counts      SendingDomainCounts    `json:"counts"`
	CheckedAt   *time.Time             `json:"checkedAt,omitempty"`
	Providers   []SenderProviderColumn `json:"providers"`
	// DMARCTip explains the DMARC suggestion; `backticks` mark code.
	DMARCTip string                `json:"dmarcTip"`
	Tracking SendingDomainTracking `json:"tracking"`
	BIMI     string                `json:"bimi"`
	Senders  int                   `json:"senders"`
	// Notes say what to do in a provider's dashboard when ReputeCast can't
	// fetch its records.
	Notes     []ProviderSetupNote `json:"notes"`
	CanManage bool                `json:"canManage"`
	// Helpers names who can manage domains when the caller can't.
	Helpers []string `json:"helpers"`
}

SendingDomainDetail is a domain's records page (and the domain step).

type SendingDomainRecord

type SendingDomainRecord struct {
	// Key identifies the row (provider, purpose, type and name).
	Key        string `json:"key"`
	ProviderID string `json:"providerId"`
	// Provider is the provider's name; empty for domain-wide records (DMARC).
	Provider   string     `json:"provider"`
	Purpose    string     `json:"purpose" enum:"dkim,return_path,spf,dmarc,verification"`
	Label      string     `json:"label"`
	Note       string     `json:"note"`
	Type       string     `json:"type"`
	Name       string     `json:"name"`
	Value      string     `json:"value"`
	Status     string     `json:"status" enum:"verified,pending,wrong_value,missing,error"`
	StatusText string     `json:"statusText"`
	Found      string     `json:"found,omitempty"`
	CheckedAt  *time.Time `json:"checkedAt,omitempty"`
	// ZoneLine is the record as a BIND zone-file line ("Copy as zone file").
	ZoneLine string `json:"zoneLine"`
}

SendingDomainRecord is one row of a domain's records table.

type SendingDomainRow

type SendingDomainRow struct {
	ID     string `json:"id"`
	Domain string `json:"domain"`
	Note   string `json:"note"`
	Status string `json:"status" enum:"pending,verified,partial,failed"`
	// UsedBy are the short names of the providers set up for the domain.
	UsedBy     []string         `json:"usedBy"`
	DKIM       SenderDomainCell `json:"dkim"`
	SPF        SenderDomainCell `json:"spf"`
	DMARC      SenderDomainCell `json:"dmarc"`
	ReturnPath SenderDomainCell `json:"returnPath"`
	Tracking   SenderDomainCell `json:"tracking"`
	BIMI       SenderDomainCell `json:"bimi"`
	Senders    int              `json:"senders"`
	CheckedAt  *time.Time       `json:"checkedAt,omitempty"`
}

SendingDomainRow is one row of "Domains".

type SendingDomainTracking

type SendingDomainTracking struct {
	Domain string `json:"domain"`
	// Suggested is the name ReputeCast proposes (go.<domain>).
	Suggested string `json:"suggested"`
	// Target is what the CNAME must point to (ReputeCast's public host).
	Target string `json:"target"`
	Status string `json:"status" enum:"none,pending,verified,wrong_value,missing,error"`
}

SendingDomainTracking is the custom link-tracking domain.

type Service

type Service struct {
	Pool    *pgxpool.Pool
	Q       *store.Queries
	Audit   *audit.Logger
	Factory *manage.Factory
	DNS     dnscheck.Resolver
	// NS returns the nameservers of a zone; nil skips the lookup.
	NS func(ctx context.Context, name string) ([]string, error)
	// TTL returns how long resolvers may cache a record set; nil skips it.
	TTL TTLFunc
	// URLs is the instance's public URL (App.URLs): custom tracking domains
	// point to its host.
	URLs       publicurl.Builder
	Cloudflare *Cloudflare
	Jobs       func() *jobs.Client
	Log        *slog.Logger
	Now        func() time.Time
	// contains filtered or unexported fields
}

Service is the senders and domains domain.

func (*Service) AddViaCloudflare

func (s *Service) AddViaCloudflare(ctx context.Context, ws *store.Workspace, rawID, token string) (SendingDomainCloudflareResult, error)

AddViaCloudflare creates or updates the domain's unverified records in its Cloudflare zone, then checks DNS again.

func (*Service) AttachProvider

func (s *Service) AttachProvider(ctx context.Context, ws *store.Workspace, domainID, providerID uuid.UUID) (string, error)

AttachProvider stores the records a provider needs for a domain (from its domain API when it has one), adds the domain-wide DMARC record when missing and checks everything live. It returns a note when the person has to add the domain in the provider's dashboard themselves.

func (*Service) Check

Check runs a live DNS check of a sending domain: every required record, the provider's own verdict where its API reports one, the authentication summary, the tracking domain and the nameservers; then it updates the verification of the domain's senders. Nothing here calls the API of a demo provider.

func (*Service) CheckIfStale

func (s *Service) CheckIfStale(ctx context.Context, d store.SendingDomain) (store.SendingDomain, error)

CheckIfStale checks a domain unless it was checked moments ago (the domain step polls every 30 seconds).

func (*Service) CreateDomain

CreateDomain adds a sending domain and asks every connected provider for the records it needs.

func (*Service) CreateSender

func (s *Service) CreateSender(ctx context.Context, ws *store.Workspace, in SenderInput) (SenderIdentity, error)

CreateSender adds a sender identity on a sending domain of the workspace.

func (*Service) DeleteDomain

func (s *Service) DeleteDomain(ctx context.Context, ws *store.Workspace, rawID string) error

DeleteDomain removes a sending domain that no sender uses any more.

func (*Service) DeleteSender

func (s *Service) DeleteSender(ctx context.Context, ws *store.Workspace, rawID string) error

DeleteSender removes a sender. Unsent campaigns that used it lose their From and must pick another before sending.

func (*Service) Detail

func (s *Service) Detail(ctx context.Context, ws *store.Workspace, rawID, providerFilter string, refresh bool) (SendingDomainDetail, error)

Detail returns a domain's records, optionally only those one provider needs (plus the domain-wide ones), after a live check when refresh is set and the last one is older than 20 seconds.

func (*Service) DetailFor

func (s *Service) DetailFor(ctx context.Context, ws *store.Workspace, d store.SendingDomain, providerFilter string) (SendingDomainDetail, error)

DetailFor builds the records page of a domain, for the connect flow.

func (*Service) DomainByName

func (s *Service) DomainByName(ctx context.Context, wsID uuid.UUID, name string) (store.SendingDomain, error)

DomainByName is the workspace's sending domain with that name, if any.

func (*Service) EnsureDomain

func (s *Service) EnsureDomain(ctx context.Context, ws *store.Workspace, name string) (store.SendingDomain, error)

EnsureDomain returns the workspace's sending domain with that name, creating it (with domains:manage) when it doesn't exist yet.

func (*Service) Overview

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

Overview returns Settings › Senders.

func (*Service) SaveDefaults

func (s *Service) SaveDefaults(ctx context.Context, ws *store.Workspace, in SenderDefaultsInput) (SenderDefaults, error)

SaveDefaults saves the "Defaults" card.

func (*Service) Sender

func (s *Service) Sender(ctx context.Context, ws *store.Workspace, id uuid.UUID) (SenderIdentity, error)

func (*Service) SenderByID

func (s *Service) SenderByID(ctx context.Context, wsID, id uuid.UUID) (store.SenderGetRow, error)

SenderByID is a sender of the workspace (system mail, the connect flow).

func (*Service) UpdateDomain

func (s *Service) UpdateDomain(ctx context.Context, ws *store.Workspace, rawID string, in UpdateDomainInput) (store.SendingDomain, error)

UpdateDomain changes a domain's note ("rename") or tracking domain.

func (*Service) UpdateSender

func (s *Service) UpdateSender(ctx context.Context, ws *store.Workspace, rawID string, in SenderInput) (SenderIdentity, error)

UpdateSender changes a sender's name, reply-to, note, default streams and the providers that never send as it.

type TTLFunc

type TTLFunc func(ctx context.Context, name, rrtype string) (time.Duration, error)

TTLFunc returns how long resolvers may cache the records of a type at a name ("Pending · old value still cached (TTL 3600)").

func LookupTTL

func LookupTTL(servers []string, timeout time.Duration) TTLFunc

LookupTTL asks the resolvers (host or host:port; empty means the system's from /etc/resolv.conf) for the records of a type at a name and returns their lowest TTL: how long a resolver may still serve the value it has cached.

type UpdateDomainInput

type UpdateDomainInput struct {
	Note *string `json:"note,omitempty" maxLength:"120"`
	// TrackingDomain is a subdomain that CNAMEs to ReputeCast so links and
	// the open pixel use the sender's domain ("" removes it).
	TrackingDomain *string `json:"trackingDomain,omitempty" maxLength:"253"`
}

UpdateDomainInput changes a domain's note or tracking domain.

Jump to

Keyboard shortcuts

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