orderedheaders

README

orderedheaders

Header parsing retaining order in Go

textproto includes a very nice MIME header parser. But it returns all the headers as a map, meaning it loses any ordering information.

For MIME headers that's seldom a problem, but for email headers it can occasionally be.

This package provides an alternate representation of headers read from a textproto reader as a list of key, value pairs. It also includes a few helper functions that are compatible with those in the textproto and mail packages.

Documentation

Overview

Package orderedheaders provides a representation of email headers and a way to read them from a textproto.Reader.

Index

• Constants
• Variables
• type Header
  • func ReadHeader(r *textproto.Reader) (Header, error)
  • func (h *Header) Add(key, value string)
  • func (h *Header) AddressList(key string) ([]*mail.Address, error)
  • func (h *Header) Bytes(o Options) ([]byte, error)
  • func (h *Header) Date() (time.Time, error)
  • func (h *Header) Get(key string) string
  • func (h *Header) Normalize()
  • func (h *Header) RemoveAll(key string)
  • func (h *Header) Set(key, value string) error
  • func (h *Header) ToMap() textproto.MIMEHeader
  • func (h *Header) WriteTo(w io.Writer, o Options) error
• type HeaderType
  • func HeaderTypeString(s string) (HeaderType, error)
  • func HeaderTypeValues() []HeaderType
  • func (i HeaderType) IsAHeaderType() bool
  • func (i HeaderType) MarshalJSON() ([]byte, error)
  • func (i HeaderType) String() string
  • func (i *HeaderType) UnmarshalJSON(data []byte) error
• type KV
• type Message
  • func ReadMessage(r io.Reader) (*Message, error)
• type Options
• type Syntax

Constants

const (
	HdrReturnPath              = "Return-Path"
	HdrReceived                = "Received"
	HdrDate                    = "Date"
	HdrFrom                    = "From"
	HdrSender                  = "Sender"
	HdrReplyTo                 = "Reply-To"
	HdrTo                      = "To"
	HdrCc                      = "Cc"
	HdrBcc                     = "Bcc"
	HdrMessageId               = "Message-Id"
	HdrInReplyTo               = "In-Reply-To"
	HdrReferences              = "References"
	HdrSubject                 = "Subject"
	HdrComments                = "Comments"
	HdrKeywords                = "Keywords"
	HdrResentDate              = "Resent-Date"
	HdrResentFrom              = "Resent-From"
	HdrResentSender            = "Resent-Sender"
	HdrResentTo                = "Resent-To"
	HdrResentCc                = "Resent-Cc"
	HdrResentBcc               = "Resent-Bcc"
	HdrMimeVersion             = "Mime-Version"
	HdrContentType             = "Content-Type"
	HdrContentID               = "Content-ID"
	HdrContentTransferEncoding = "Content-Transfer-Encoding"
	HdrContentDescription      = "Content-Description"
)

Variables

var HeaderSyntax = map[string]Syntax{
	HdrReturnPath:              {Type: HeaderTypeReturnPath},
	HdrReceived:                {Type: HeaderTypeReceived},
	HdrDate:                    {Required: true, Unique: true, Type: HeaderTypeDate},
	HdrFrom:                    {Required: true, Unique: true, Type: HeaderTypeMailboxList},
	HdrSender:                  {Unique: true, Type: HeaderTypeMailbox},
	HdrReplyTo:                 {Unique: true, Type: HeaderTypeMailboxList},
	HdrTo:                      {Unique: true, Type: HeaderTypeMailboxList},
	HdrCc:                      {Unique: true, Type: HeaderTypeMailboxList},
	HdrBcc:                     {Unique: true, Type: HeaderTypeMailboxList},
	HdrMessageId:               {Unique: true, Type: HeaderTypeMessageID},
	HdrInReplyTo:               {Unique: true, Type: HeaderTypeMessageIDList},
	HdrReferences:              {Unique: true, Type: HeaderTypeMessageIDList},
	HdrSubject:                 {Unique: true, Type: HeaderTypeUnstructured},
	HdrComments:                {Type: HeaderTypeUnstructured},
	HdrKeywords:                {Type: HeaderTypePhraseList},
	HdrResentDate:              {Type: HeaderTypeDate},
	HdrResentFrom:              {Type: HeaderTypeMailboxList},
	HdrResentSender:            {Type: HeaderTypeMailbox},
	HdrResentTo:                {Type: HeaderTypeMailboxList},
	HdrResentCc:                {Type: HeaderTypeMailboxList},
	HdrResentBcc:               {Type: HeaderTypeMailboxList},
	HdrMimeVersion:             {Unique: true, Type: HeaderTypeOpaque},
	HdrContentType:             {Unique: true, Type: HeaderTypeOpaque},
	HdrContentID:               {Unique: true, Type: HeaderTypeMessageID},
	HdrContentTransferEncoding: {Unique: true, Type: HeaderTypeOpaque},
	HdrContentDescription:      {Unique: true, Type: HeaderTypeUnstructured},
}

HeaderSyntax maps header names to their syntax

Types

type Header

type Header struct {
	Headers []KV
}

A Header represents a MIME-style header consisting of a list of key, value pairs

func ReadHeader

func ReadHeader(r *textproto.Reader) (Header, error)

ReadHeader reads a MIME-style header from r, much like textproto.ReadMIMEHeader. The returned value is a list of key, value pairs

func (*Header) Add

func (h *Header) Add(key, value string)

Add adds a new key, value pair to the header

func (*Header) AddressList

func (h *Header) AddressList(key string) ([]*mail.Address, error)

AddressList parses the named header field as a list of addresses.

func (*Header) Bytes

func (h *Header) Bytes(o Options) ([]byte, error)

func (*Header) Date

func (h *Header) Date() (time.Time, error)

Date parses the Date header field.

func (*Header) Get

func (h *Header) Get(key string) string

Get gets the first value associated with the given key. It is case-insensitive; CanonicalMIMEHeaderKey is used to canonicalize the provided key. If there are no values associated with the key, Get returns "".

func (*Header) Normalize

func (h *Header) Normalize()

Normalize replaces all whitespace in a header with a single space.

func (*Header) RemoveAll

func (h *Header) RemoveAll(key string)

RemoveAll removes all headers with this (canonicalized) name

func (*Header) Set

func (h *Header) Set(key, value string) error

Set sets a standard header, replacing any existing one. It only accepts standard email headers, not extensions.

func (*Header) ToMap

func (h *Header) ToMap() textproto.MIMEHeader

ToMap converts a Header to a textproto.MIMEHeader

func (*Header) WriteTo

func (h *Header) WriteTo(w io.Writer, o Options) error

type HeaderType

type HeaderType int

HeaderType describes the required syntax for an email header

const (
	HeaderTypeUnstructured HeaderType = iota
	HeaderTypeMailbox
	HeaderTypeMailboxList
	HeaderTypeDate
	HeaderTypeReceived
	HeaderTypeMessageID
	HeaderTypeMessageIDList
	HeaderTypePhraseList
	HeaderTypeReturnPath
	HeaderTypeOpaque
)

func HeaderTypeString

func HeaderTypeString(s string) (HeaderType, error)

HeaderTypeString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func HeaderTypeValues

func HeaderTypeValues() []HeaderType

HeaderTypeValues returns all values of the enum

func (HeaderType) IsAHeaderType

func (i HeaderType) IsAHeaderType() bool

IsAHeaderType returns "true" if the value is listed in the enum definition. "false" otherwise

func (HeaderType) MarshalJSON

func (i HeaderType) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for HeaderType

func (HeaderType) String

func (i HeaderType) String() string

func (*HeaderType) UnmarshalJSON

func (i *HeaderType) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for HeaderType

type KV

type KV struct {
	Key   string
	Value string
}

A KV represents a single mime header

type Message

type Message struct {
	Header Header
	Body   io.Reader
}

func ReadMessage

func ReadMessage(r io.Reader) (*Message, error)

type Options

type Options struct {
	// RenderBCC enables rendering the Bcc: header, which is ignored by default
	RenderBCC bool
	// RenderBlank enables rendering headers which have zero length content
	RenderBlank bool
	// NoEscape disables encoding of non-ASCI content in a header
	NoEscape bool
}

Options configures how a set of headers will be rendered.

type Syntax

type Syntax struct {
	Required bool
	Unique   bool
	Type     HeaderType
}

Syntax contains RFC 5322 requirements for a header