Documentation
¶
Overview ¶
Package aliases implements an email aliases resolver.
The resolver can parse many files for different domains, and perform lookups to resolve the aliases.
File format ¶
It generally follows the traditional aliases format used by sendmail and exim.
The file can contain lines of the form:
user: address, address user: | command
Lines starting with "#" are ignored, as well as empty lines. User names cannot contain spaces, ":" or commas, for parsing reasons. This is a tradeoff between flexibility and keeping the file format easy to edit for people.
User names will be normalized internally to lower-case.
Usually there will be one database per domain, and there's no need to include the "@" in the user (in this case, "@" will be forbidden).
If the user is the string "*", then it is considered a "catch-all alias": emails that don't match any known users or other aliases will be sent here.
Recipients ¶
Recipients can be of different types:
- Email: the usual user@domain we all know and love, this is the default.
- Pipe: if the right side starts with "| ", the rest of the line specifies a command to pipe the email through. Command and arguments are space separated. No quoting, escaping, or replacements of any kind.
Lookups ¶
The resolver will perform lookups recursively, until it finds all the final recipients.
There are recursion limits to avoid alias loops. If the limit is reached, the entire resolution will fail.
Suffix removal ¶
The resolver can also remove suffixes from emails, and drop characters completely. This can be used to turn "user+blah@domain" into "user@domain", and "us.er@domain" into "user@domain".
Both are optional, and the characters configurable globally.
There are more complex semantics around handling of drop characters and suffixes, see the documentation for more details.
Index ¶
- Variables
- type RType
- type Recipient
- type Resolver
- func (v *Resolver) AddAliasForTesting(addr, rcpt string, rType RType)
- func (v *Resolver) AddAliasesFile(domain, path string) error
- func (v *Resolver) AddDomain(domain string)
- func (v *Resolver) Exists(tr *trace.Trace, addr string) bool
- func (v *Resolver) Reload() error
- func (v *Resolver) RemoveDropCharacters(addr string) string
- func (v *Resolver) RemoveDropsAndSuffix(addr string) string
- func (v *Resolver) Resolve(tr *trace.Trace, addr string) ([]Recipient, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRecursionLimitExceeded is returned when the resolving lookup // exceeded the recursion limit. Usually caused by aliases loops. ErrRecursionLimitExceeded = fmt.Errorf("recursion limit exceeded") )
Functions ¶
This section is empty.
Types ¶
type RType ¶
type RType string
RType represents a recipient type, see the constants below for valid values.
type Recipient ¶
Recipient represents a single recipient, after resolving aliases. They don't have any special interface, the callers will do a type switch anyway.
type Resolver ¶
type Resolver struct {
// Suffix separator, to perform suffix removal.
SuffixSep string
// Characters to drop from the user part.
DropChars string
// Path to the resolve hook.
ResolveHook string
// contains filtered or unexported fields
}
Resolver represents the aliases resolver.
func NewResolver ¶
func NewResolver(userExists existsFn) *Resolver
NewResolver returns a new, empty Resolver.
func (*Resolver) AddAliasForTesting ¶
AddAliasForTesting adds an alias to the resolver, for testing purposes. Not for use in production code.
func (*Resolver) AddAliasesFile ¶
AddAliasesFile to the resolver. The file will be parsed, and an error returned if it does not exist or parse correctly.
func (*Resolver) Exists ¶
Exists check that the address exists in the database. It must only be called for local addresses.
func (*Resolver) RemoveDropCharacters ¶ added in v1.13.0
Remove drop characters, but only up to the first suffix separator.
Source Files