Documentation
¶
Overview ¶
Package email holds what backd knows about the emails it asks a realm's delivery function to send: the kinds, the templates (loaded from <realm>/email/ into memory at startup and rendered per message), and the shape of the message handed to the function. backd never sends mail itself.
Index ¶
Constants ¶
const ( VerifyEmail = "verify-email" ResetPassword = "reset-password" AccountExists = "account-exists" PasswordChanged = "password-changed" Welcome = "welcome" ChangeEmail = "change-email" EmailChanged = "email-changed" Invitation = "invitation" )
The kinds of email backd sends on its own.
const ( PageVerifyEmail = "verify-email" PageResetPassword = "reset-password" PageConfirmEmailChange = "confirm-email-change" PageRevertEmailChange = "revert-email-change" PageAcceptInvitation = "accept-invitation" PageResult = "result" PageInvalidToken = "invalid-token" )
The hosted pages. The first five are the forms a link opens; Result is shown after an action succeeds, InvalidToken for any link that doesn't work.
const DirName = "email"
DirName is the folder of a realm that holds its email templates.
const PagesDirName = "pages"
PagesDirName is the folder of a realm that holds its hosted pages: the pages the links in emails open (<realm>/pages/<kind>/<locale>.html).
Variables ¶
var PageKinds = []string{PageVerifyEmail, PageResetPassword, PageConfirmEmailChange, PageRevertEmailChange, PageAcceptInvitation, PageResult, PageInvalidToken}
PageKinds are the pages every realm that sends email has, in every language it lists.
var RequiredKinds = []string{VerifyEmail, ResetPassword, AccountExists, PasswordChanged}
RequiredKinds must have a template in every realm that configures email.
var SystemKinds = []string{VerifyEmail, ResetPassword, AccountExists, PasswordChanged, Welcome, ChangeEmail, EmailChanged, Invitation}
SystemKinds are the kinds backd knows; `backd template realm` writes an English template for each.
Functions ¶
func DefaultFiles ¶
DefaultFiles returns the English template files of a system kind, by file name (en.subject.txt, en.txt, en.html).
func DefaultPage ¶
DefaultPage returns the English template of a hosted page.
func ValidLocale ¶
ValidLocale reports whether v looks like a BCP 47 language tag (es, es-MX).
Types ¶
type Data ¶
Data is what a template can use: {{.Realm}}, {{.User.Email}}, {{.User.Locale}}, {{.Link}}, {{.ExpiresAt}} and {{.Data}}. Templates never receive text written by whoever caused the email, so backd can't be used to send someone else's words.
type PageData ¶
type PageData struct {
Realm string
Locale string
Action string
Token string
Error string
// ErrorCode names the problem in Error (password_mismatch, password_policy)
// so a template can write it in its own words.
ErrorCode string
Kind string
// Email is the address the link is about: the new one for a change, the
// previous one for an undo, the invited one for an invitation.
Email string
// Redirect and BackURL are checked against the realm's allowed_redirects
// before they get here, so they may use an app's own scheme (acme://),
// which html/template would otherwise refuse in a link.
Redirect htmltemplate.URL
DelaySeconds int
BackURL htmltemplate.URL
}
PageData is what a page template can use: {{.Realm}}, {{.Locale}}, {{.Action}} (where its form posts), {{.Token}} (the hidden field), {{.Error}} and {{.ErrorCode}} (what to show on the form again), {{.Kind}} (which flow a result is for), {{.Email}} (the address the link is about), {{.Redirect}} and {{.DelaySeconds}} (where the result sends the user and when), {{.BackURL}} (a way back to the app on the error page).
type Pages ¶
type Pages struct {
// contains filtered or unexported fields
}
Pages are a realm's parsed hosted pages, held in memory.
func LoadPages ¶
LoadPages reads <realm>/pages/ (dir): <kind>/<locale>.html for every kind of PageKinds and every one of locales. It parses and test-renders each page, and reports every problem together, naming the files.
type Purpose ¶
type Purpose string
Purpose is what a token created for an email can be redeemed for.
func TokenPurpose ¶
TokenPurpose returns the token an email of this kind carries, or "" when the kind has no link with a token.
func (Purpose) DefaultLifetime ¶
DefaultLifetime is how long a token of this purpose can be redeemed.
type Templates ¶
type Templates struct {
// contains filtered or unexported fields
}
Templates are a realm's parsed templates, held in memory.
func Load ¶
Load reads <realm>/email/ (dir): one folder per kind, with <locale>.subject.txt, <locale>.txt and <locale>.html per locale. It parses and test-renders every template, requires the RequiredKinds, and requires every kind found to be complete in every one of locales. Problems are reported together, naming the files.