imap

README

MailHog IMAP Protocol

github.com/mailhog/imap implements an IMAP server state machine.

It attempts to encapsulate as much of the IMAP protocol (plus its extensions) as possible without compromising configurability or requiring specific backend implementations.

See MailHog-IMAP for an example implementation.

Licence

Copyright ©‎ 2015, Ian Kent (http://iankent.uk)

Released under MIT license, see LICENSE for details.

Documentation

Index

• Constants
• Variables
• type Capability
• type Command
  • func ParseCommand(line string) *Command
• type GenericCapability
  • func (gc *GenericCapability) Available(p *Protocol) bool
  • func (gc *GenericCapability) Name() string
• type Protocol
  • func NewProtocol(responses chan *Response) *Protocol
  • func (proto *Protocol) AUTHENTICATE(command *Command)
  • func (proto *Protocol) CAPABILITY(cmd *Command)
  • func (proto *Protocol) CREATE(command *Command)
  • func (proto *Protocol) Command(command *Command)
  • func (proto *Protocol) Parse(line string) string
  • func (proto *Protocol) ProcessCommand(line string)
  • func (proto *Protocol) SELECT(command *Command)
  • func (proto *Protocol) STARTTLS(command *Command)
  • func (proto *Protocol) Start() *Response
• type Response
  • func ResponseBye() *Response
  • func ResponseError(tag string, err error) *Response
  • func ResponseIdent(revision, hostname, ident string) *Response
  • func ResponseLineTooLong(tag string) *Response
  • func ResponseReadyToStartTLS(tag string, done func()) *Response
  • func ResponseSyntaxError(tag string) *Response
  • func ResponseUnrecognisedCommand(tag string) *Response
  • func (r Response) Lines() []string
• type ResponseCode
  • func Code(r ResponseCode) *ResponseCode
• type ResponseStatus
  • func Status(r ResponseStatus) *ResponseStatus
• type State

Constants

const (
	// ResponseOK represents an OK response
	ResponseOK = ResponseStatus(iota)
	// ResponseNO represents a NO response
	ResponseNO
	// ResponseBAD represents a BAD response
	ResponseBAD
	// ResponsePREAUTH represents a PREAUTH response
	ResponsePREAUTH
	// ResponseBYE represents a BYE response
	ResponseBYE
)

const (
	// ALERT represents the ALERT response code
	ALERT = ResponseCode("ALERT")
	// BADCHARSET represents the BADCHARSET response code
	BADCHARSET = ResponseCode("BADCHARSET")
	// CAPABILITY represents the CAPABILITY response code
	CAPABILITY = ResponseCode("CAPABILITY")
	// PARSE represents the PARSE response code
	PARSE = ResponseCode("PARSE")
	// PERMANENTFLAGS represents the PERMANENTFLAGS response code
	PERMANENTFLAGS = ResponseCode("PERMANENTFLAGS")
	// READONLY represents the READ-ONLY response code
	READONLY = ResponseCode("READ-ONLY")
	// READWRITE represents the READ-WRITE response code
	READWRITE = ResponseCode("READ-WRITE")
	// TRYCREATE represents the TRYCREATE response code
	TRYCREATE = ResponseCode("TRYCREATE")
	// UIDNEXT represents the UIDNEXT response code
	UIDNEXT = ResponseCode("UIDNEXT")
	// UIDVALIDITY represents the UIDVALIDITY response code
	UIDVALIDITY = ResponseCode("UIDVALIDITY")
	// UNSEEN represents the UNSEEN response code
	UNSEEN = ResponseCode("UNSEEN")
)

const (
	INVALID = State(-1)
	PREAUTH = State(iota)
	AUTH
	SELECTED
	LOGOUT
)

IMAP message conversation states

Variables

var ResponseStatusMapping = map[ResponseStatus]string{
	ResponseOK:      "OK",
	ResponseNO:      "NO",
	ResponseBAD:     "BAD",
	ResponsePREAUTH: "PREAUTH",
	ResponseBYE:     "BYE",
}

ResponseStatusMapping is the text representation of a ResponseStatus

var StateMap = map[State]string{
	INVALID:  "INVALID",
	PREAUTH:  "PREAUTH",
	AUTH:     "AUTH",
	SELECTED: "SELECTED",
	LOGOUT:   "LOGOUT",
}

StateMap provides string representations of IMAP conversation states

Types

type Capability

type Capability interface {
	Name() string
	Available(p *Protocol) bool
}

Capability represents an IMAP capability

type Command

type Command struct {
	// contains filtered or unexported fields
}

Command is a struct representing an SMTP command (verb + arguments)

func ParseCommand

func ParseCommand(line string) *Command

ParseCommand returns a Command from the line string

type GenericCapability

type GenericCapability struct {
	// contains filtered or unexported fields
}

GenericCapability represents a generic IMAP4rev1 capability

func (*GenericCapability) Available

func (gc *GenericCapability) Available(p *Protocol) bool

Available implements Capability.Available

func (*GenericCapability) Name

func (gc *GenericCapability) Name() string

Name implements Capability.Name

type Protocol

type Protocol struct {
	TLSPending  bool
	TLSUpgraded bool

	State     State
	Responses chan *Response

	Hostname string
	Ident    string
	Revision string

	MaximumLineLength int

	Capabilities map[string]Capability

	// LogHandler is called for each log message. If nil, log messages will
	// be output using log.Printf instead.
	LogHandler func(message string, args ...interface{})
	// ValidateAuthenticationhandler should return true if the authentication
	// parameters are valid, otherwise false. If nil, all authentication
	// attempts will be accepted.
	ValidateAuthenticationHandler func(mechanism string, args ...string) (ok bool)
	// TLSHandler is called when a STARTTLS command is received.
	//
	// It should acknowledge the TLS request and set ok to true.
	// It should also return a callback which will be invoked after the Response is
	// sent. E.g., a TCP connection can only perform the upgrade after sending the Response
	//
	// Once the upgrade is complete, invoke the done function (e.g., from the returned callback)
	//
	// If TLS upgrade isn't possible, return an errorResponse and set ok to false.
	TLSHandler func(done func(ok bool)) (errorResponse *Response, callback func(), ok bool)

	// GetAuthenticationMechanismsHandler should return an array of strings
	// listing accepted authentication mechanisms
	GetAuthenticationMechanismsHandler func() []string

	// RequireTLS controls whether TLS is required for a connection before other
	// commands can be issued, applied at the protocol layer.
	RequireTLS bool
	// contains filtered or unexported fields
}

Protocol is a state machine representing an SMTP session

func NewProtocol

func NewProtocol(responses chan *Response) *Protocol

NewProtocol returns a new SMTP state machine in INVALID state

func (*Protocol) AUTHENTICATE

func (proto *Protocol) AUTHENTICATE(command *Command)

AUTHENTICATE implements RFC3501 AUTHENTICATE command

func (*Protocol) CAPABILITY

func (proto *Protocol) CAPABILITY(cmd *Command)

CAPABILITY implements RFC3501 CAPABILITY command

func (*Protocol) CREATE

func (proto *Protocol) CREATE(command *Command)

CREATE implements RFC3501 CREATE command

func (*Protocol) Command

func (proto *Protocol) Command(command *Command)

Command applies an SMTP verb and arguments to the state machine

func (*Protocol) Parse

func (proto *Protocol) Parse(line string) string

Parse parses a line string and returns any remaining line string and a Response, if a command was found. Parse does nothing until a new line is found.

• TODO decide whether to move this to a buffer inside Protocol sort of like it this way, since it gives control back to the caller

func (*Protocol) ProcessCommand

func (proto *Protocol) ProcessCommand(line string)

ProcessCommand processes a line of text as a command It expects the line string to be a properly formed SMTP verb and arguments

func (*Protocol) SELECT

func (proto *Protocol) SELECT(command *Command)

SELECT implements RFC3501 SELECT command

func (*Protocol) STARTTLS

func (proto *Protocol) STARTTLS(command *Command)

STARTTLS creates a Response to a STARTTLS command

func (*Protocol) Start

func (proto *Protocol) Start() *Response

Start begins an IMAP conversation with an OK response, placing the state machine in PREAUTH state.

type Response

type Response struct {
	Tag    string
	Status *ResponseStatus
	Code   *ResponseCode
	Text   string
	Done   func()
}

Response is a struct representing an IMAP response

func ResponseBye

func ResponseBye() *Response

ResponseBye returns an untagged BYE response

func ResponseError

func ResponseError(tag string, err error) *Response

ResponseError returns a BAD response containing the error text

func ResponseIdent

func ResponseIdent(revision, hostname, ident string) *Response

ResponseIdent returns an OK server ready response

func ResponseLineTooLong

func ResponseLineTooLong(tag string) *Response

ResponseLineTooLong returns a BAD error response

func ResponseReadyToStartTLS

func ResponseReadyToStartTLS(tag string, done func()) *Response

ResponseReadyToStartTLS returns a tagged OK response

func ResponseSyntaxError

func ResponseSyntaxError(tag string) *Response

ResponseSyntaxError returns a tagged syntax error response

func ResponseUnrecognisedCommand

func ResponseUnrecognisedCommand(tag string) *Response

ResponseUnrecognisedCommand returns a tagged unrecognised command response

func (Response) Lines

func (r Response) Lines() []string

Lines returns the formatted SMTP reply

type ResponseCode

type ResponseCode string

ResponseCode represents an IMAP response code

func Code

func Code(r ResponseCode) *ResponseCode

Code returns a pointer to a ResponseCode value

type ResponseStatus

type ResponseStatus int

ResponseStatus represents an IMAP response status

func Status

func Status(r ResponseStatus) *ResponseStatus

Status returns a pointer to a ResponseStatus value

type State

type State int

State represents the state of an IMAP conversation