planjson

Documentation

Overview

Package planjson projects mailctl's plan and audit results into a stable JSON schema. Both `mailctl plan -json` and the local UI server render through it, so a script gating a pipeline and the UI can never disagree about what a run intends to do.

Index

• Constants
• type Action
• type Alias
• type BIMI
• type CatchAll
• type Check
• type DMARC
• type Deliverability
• type Domain
• type Domains
  • func FromDomains(domains []config.Domain) Domains
• type MTASts
• type Mailbox
• type Plan
  • func FromPlan(p plan.Plan) Plan
• type Report
  • func FromReport(r audit.Report) Report

Constants

const SchemaVersion = 1

SchemaVersion is incremented when a change would break an existing consumer. Adding a field is not such a change; removing or repurposing one is.

Types

type Action

type Action struct {
	// ID identifies the action within this plan only. It is a position, not a
	// durable identity, and it is not stable across runs.
	ID       string `json:"id"`
	Op       string `json:"op"`
	Resource string `json:"resource"`
	Domain   string `json:"domain"`
	Provider string `json:"provider,omitempty"`
	Detail   string `json:"detail"`
	// Manual marks an action a human completes outside mailctl. It renders in
	// the plan and is never executed, so a converged plan may still list one.
	Manual bool `json:"manual"`
}

Action is one intended change, described but not executable.

plan.Action carries Do, a closure over live provider clients. It is deliberately absent here: this type describes intent, and a plan that has been through JSON must never be a way to ask for work. Apply resolves actions from a plan it holds itself.

type Alias

type Alias struct {
	Match string   `json:"match"`
	To    []string `json:"to"`
}

type BIMI

type BIMI struct {
	Logo string `json:"logo"`
	VMC  string `json:"vmc,omitempty"`
}

type CatchAll

type CatchAll struct {
	To []string `json:"to"`
}

type Check

type Check struct {
	Name string `json:"name"`
	Want string `json:"want"`
	Got  string `json:"got"`
	OK   bool   `json:"ok"`
}

type DMARC

type DMARC struct {
	Policy          string `json:"policy"`
	SubdomainPolicy string `json:"subdomainPolicy,omitempty"`
	Pct             int    `json:"pct,omitempty"`
	RUA             string `json:"rua,omitempty"`
	RUF             string `json:"ruf,omitempty"`
}

type Deliverability

type Deliverability struct {
	SPFIncludes []string `json:"spfIncludes"`
	DMARC       *DMARC   `json:"dmarc,omitempty"`
	MTASts      *MTASts  `json:"mtaSts,omitempty"`
	TLSRpt      string   `json:"tlsRpt,omitempty"`
	BIMI        *BIMI    `json:"bimi,omitempty"`
}

type Domain

type Domain struct {
	Name           string         `json:"name"`
	Zone           string         `json:"zone"`
	Providers      []string       `json:"providers"`
	Mailboxes      []Mailbox      `json:"mailboxes"`
	Aliases        []Alias        `json:"aliases"`
	CatchAll       *CatchAll      `json:"catchAll,omitempty"` // absent: left alone
	Deliverability Deliverability `json:"deliverability"`
}

type Domains

type Domains struct {
	SchemaVersion int      `json:"schemaVersion"`
	Domains       []Domain `json:"domains"`
}

Domains is `mailctl domains -json`: the config as mailctl resolved it, per domain. It names the environment variable a credential comes from and never a value.

func FromDomains

func FromDomains(domains []config.Domain) Domains

type MTASts

type MTASts struct {
	Mode   string `json:"mode"`
	MaxAge int    `json:"maxAge,omitempty"`
	Deploy bool   `json:"deploy"`
}

type Mailbox

type Mailbox struct {
	Address string `json:"address"`
	// PasswordEnv names where the credential comes from; empty means mailctl
	// generates one when it creates the mailbox.
	PasswordEnv string `json:"passwordEnv,omitempty"`
	DisplayName string `json:"displayName,omitempty"`
	License     string `json:"license,omitempty"`
	Recovery    int    `json:"recovery"`
}

type Plan

type Plan struct {
	SchemaVersion int      `json:"schemaVersion"`
	Actions       []Action `json:"actions"`
}

func FromPlan

func FromPlan(p plan.Plan) Plan

type Report

type Report struct {
	Domain string   `json:"domain"`
	OK     bool     `json:"ok"`
	Checks []Check  `json:"checks"`
	Notes  []string `json:"notes"`
}

Report is one domain's audit result. OK is materialised as a field because audit.Report.OK() is a method and would otherwise be invisible to a consumer.

func FromReport

func FromReport(r audit.Report) Report