Documentation
¶
Overview ¶
Package domainverify is the module behind the Sending domain verification jobs (ADR 0010, ADR 0038): the live DKIM check and what it decides (the verified moments, the loss of verification, the Owners' notice of it), and the Tracking domain check and what it decides (a host another Workspace holds, a stale answer, a state that went back a step and its notice). The jobs only pick which domains are due and call it.
It reads a Sending domain by id to learn its Workspace, before any scope exists, so it holds the raw client (the same shape as internal/joindomains). Every write goes through the Workspace's scope.
Index ¶
- Constants
- func DevTXTLookup(client *ent.Client) sending.TXTLookup
- func ShortcutTXTLookup(client *ent.Client, upstream sending.TXTLookup) sending.TXTLookup
- type Module
- func (m *Module) Due(ctx context.Context, limit int) ([]int64, error)
- func (m *Module) TrackingDue(ctx context.Context) ([]int64, error)
- func (m *Module) Verify(ctx context.Context, id int64) error
- func (m *Module) VerifyDKIM(ctx context.Context, id int64) (verified bool, err error)
- func (m *Module) VerifyTracking(ctx context.Context, id int64) error
Constants ¶
const ShortcutDomain = "getsphericon.io"
ShortcutDomain is the one domain that verifies without DNS in a non-production Instance: a Sending domain or a Join domain on it is trusted at once, so a developer can try the flow without publishing a record. Every other domain is resolved through real DNS.
Variables ¶
This section is empty.
Functions ¶
func DevTXTLookup ¶
DevTXTLookup is the sending-domain DKIM resolver of the end-to-end suite: instead of querying real DNS (which no test domain publishes), it echoes back each domain's own stored public key, so any sending domain a scenario adds self-verifies and the send gate (ADR 0010) doesn't block the Mailpit loop. It answers a Join domain's proof record the same way: the name _sphericon-join.<domain> resolves to the tokens every Workspace's claim of the domain stores, so a domain an Owner adds in the members settings verifies without DNS. Because it answers every Workspace's token, two Workspaces claiming one domain both verify, so a hand-over (the loser of a take-over) can never fire here. A development Instance reaches it only for ShortcutDomain, through ShortcutTXTLookup.
func ShortcutTXTLookup ¶
ShortcutTXTLookup is the resolver of a development Instance: the proof records of ShortcutDomain are answered from what we stored for it (see DevTXTLookup), every other name goes to upstream. Production uses upstream alone: this trust must never be wired outside a dev env.
Types ¶
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module checks Sending domains. tracking is nil while the Tracking domain feature is off.
func New ¶
func New(client *ent.Client, lookup sending.TXTLookup, tracking *trackingdomain.Verifier, notify ownernotice.Notify) *Module
func (*Module) Due ¶
Due returns up to limit ids of the Sending domains whose DKIM is to be re-checked, least-recently-checked first with NULLS FIRST: a freshly added, never-checked domain is verified soonest rather than starved behind already-checked ones (plain ASC sorts NULLs last in Postgres). An archived domain is skipped (ADR 0049).
func (*Module) TrackingDue ¶
TrackingDue returns every Sending domain whose Tracking domain is dns_verified or serving, so a host that stops answering is demoted within one tick. An archived Sending domain is skipped, a named exception to ADR 0049's rule that job entry points include discarded rows: it serves nothing to demote. There is no batch limit and no DKIM dependency: a pending Tracking domain is only checked when its owner clicks Verify.
func (*Module) Verify ¶
Verify runs both checks of one Sending domain. The Tracking domain check is independent of DKIM: a DKIM lookup error is returned (the job retries) but never skips it.
func (*Module) VerifyDKIM ¶
VerifyDKIM re-checks a domain's DKIM DNS and persists the result: last_checked_at, verified_at when it becomes verified (clearing the loss) and verification_lost_at when it stops being. It returns the resulting verified state. A check that loses a live domain's verification mails the Owners, best-effort: a failed notice never fails the check. The write is a compare-and-swap on the state the check read, so a check that lost to another one stores nothing and reports no flip: the Owners are told once per loss (ADR 0046).
func (*Module) VerifyTracking ¶
VerifyTracking re-checks a Sending domain's Tracking domain (the CNAME, then the HTTPS probe) and stores the state (ADR 0038). No verifier (the feature is off) does nothing. A host another Workspace already holds leaves this claim pending and is not an error: retrying cannot change it. Neither is a state another check changed first (lifecycle.ErrInvalidTransition): the stale answer is dropped. A host that was dns_verified or serving and went back a step notifies the Workspace's Owners, best-effort; every change publishes its domain event inside the check.
Source Files