mail

Documentation

Overview

Package mail defines the interface every mail provider implements and the vocabulary the engine uses to talk about provider-side state.

Index

• func Register(name string, f Factory)
• func Registered() []string
• func Unregister(name string)
• type Alias
• type CatchAll
• type Deps
• type Factory
• type Mailbox
• type Options
• type Provider
  • func Open(name string, deps Deps) (Provider, error)
• type Recovery
• type Settings
• type State
  • func (s State) Alias(match string, prefix bool) (Alias, bool)
  • func (s State) Mailbox(address string) (Mailbox, bool)

Functions

func Register

func Register(name string, f Factory)

Register adds a provider factory. Providers call this from an init function and are pulled in by a blank import in cmd/mailctl, so the engine never imports a provider package directly.

func Registered

func Registered() []string

Registered returns every registered provider name, sorted.

func Unregister

func Unregister(name string)

Unregister removes a provider. It exists so tests can register fakes without leaking them into other tests.

Types

type Alias

type Alias struct {
	ID     string
	Match  string // local part, without any trailing *
	Prefix bool
	To     []string
}

type CatchAll

type CatchAll struct {
	ID string
	To []string
}

type Deps

type Deps struct {
	Cloudflare        *cfapi.Client
	AccountID         string
	PurelymailBaseURL string
	// Zones resolves a zone name to a zone ID. Providers whose API is
	// zone-scoped need it; Purelymail ignores it.
	Zones  dns.Provider
	Getenv func(string) string
	// GraphBaseURL and LoginBaseURL override the Microsoft endpoints. Tests
	// point them at httptest servers; production leaves them empty.
	GraphBaseURL string
	LoginBaseURL string
}

Deps is everything a provider factory may need. A factory takes only what it uses; adding a field here does not change existing providers.

type Factory

type Factory func(Deps) (Provider, error)

type Mailbox

type Mailbox struct {
	Address string
	// AlternateAddress is a second identity address config may name for this
	// same mailbox, set by providers with two distinct identity attributes
	// that can diverge (Microsoft Graph's mail and userPrincipalName, after an
	// admin changes either one independently). Address holds whichever the
	// provider prefers to display; AlternateAddress holds the other one, when
	// it differs and is non-empty. Providers with a single address identity
	// leave it empty.
	AlternateAddress string
	// ID is the provider's own object identifier for this mailbox, set by
	// providers that need one to act on a mailbox unambiguously (e.g.
	// Microsoft Graph, which resolves /users/{id} by id or userPrincipalName,
	// never by an arbitrary address). Providers that address mailboxes by name
	// leave it empty; Purelymail deletes by address via its own API, so it does.
	ID string
	// AssignedSkuIDs are the licence SKU ids already assigned to this
	// mailbox, set by providers with a licence concept so Plan can detect an
	// existing-but-unlicensed account without I/O. Purelymail leaves it empty.
	AssignedSkuIDs []string
	Recovery       []Recovery
}

type Options

type Options struct {
	// Prune plans deletion of provider-side objects absent from the config.
	Prune bool
	// PruneMailboxes allows Prune to plan mailbox deletion. It is a second
	// opt-in because deleting a mailbox destroys mail, and a prune scope wider
	// than the operator intended has already caused data loss in this project.
	PruneMailboxes bool
	// Secrets resolves mailbox credentials.
	Secrets *secret.Resolver
}

Options are the flags that change what Plan produces.

type Provider

type Provider interface {
	Name() string

	// DesiredDNS returns the records this provider needs published for the
	// domain. Providers that expose a DNS endpoint fetch them; providers that
	// do not construct them.
	DesiredDNS(ctx context.Context, d config.Domain) ([]dns.Record, error)

	// Actual reads current provider-side state for the domain.
	Actual(ctx context.Context, d config.Domain) (State, error)

	// Plan diffs the config against actual and returns ordered actions. Plan
	// performs no I/O; the returned actions carry closures that do.
	Plan(d config.Domain, actual State, opts Options) ([]plan.Action, error)
}

Provider is one mail service managing one or more domains.

func Open

func Open(name string, deps Deps) (Provider, error)

Open builds the named provider.

type Recovery

type Recovery struct {
	ID          string
	Type        string // email | phone
	Target      string
	Description string
}

type Settings

type Settings struct {
	AllowAccountReset     bool
	SymbolicSubaddressing bool
}

type State

type State struct {
	DomainExists bool
	Settings     Settings
	Mailboxes    []Mailbox
	Aliases      []Alias
	CatchAll     *CatchAll
	// Verified and SupportedServices are set by providers that have a
	// verification step; Purelymail leaves them zero.
	Verified          bool
	SupportedServices []string
	// Notes are provider observations worth showing in plan output, such as
	// "DNS check: mx=true spf=false".
	Notes []string
}

State is provider-side reality for one domain.

func (State) Alias

func (s State) Alias(match string, prefix bool) (Alias, bool)

Alias returns the state entry matching a local part and prefix flag.

func (State) Mailbox

func (s State) Mailbox(address string) (Mailbox, bool)

Mailbox returns the state entry for an address, and whether it exists. A match on AlternateAddress counts too, so a provider whose two identity attributes have diverged is still found by whichever one config names.