milter

README

milter

A Go library for milter support heavily inspired from https://github.com/andybalholm/milter For example how to use the library see https://github.com/phalaaxx/pf-milters - postfix milter for email classification with bogofilter and blacklisting messages which contain files with executable extensions.

Documentation

Overview

A Go library for milter support

Index

• Constants
• func Close() (err error)
• func RunServer(server net.Listener, init MilterInit, handlers ...func(error)) error
• type CustomResponse
  • func NewResponse(code byte, data []byte) *CustomResponse
  • func NewResponseStr(code byte, data string) *CustomResponse
  • func (c *CustomResponse) Continue() bool
  • func (c *CustomResponse) Response() *Message
• type Message
• type Milter
• type MilterInit
• type Modifier
  • func (m *Modifier) AddHeader(name, value string) error
  • func (m *Modifier) AddRecipient(r string) error
  • func (m *Modifier) ChangeHeader(index int, name, value string) error
  • func (m *Modifier) DeleteRecipient(r string) error
  • func (m *Modifier) Quarantine(reason string) error
  • func (m *Modifier) ReplaceBody(body []byte) error
• type OptAction
• type OptProtocol
• type Response
• type Server
  • func (s *Server) Close() (err error)
  • func (s *Server) RunServer() error
• type SimpleResponse
  • func (r SimpleResponse) Continue() bool
  • func (r SimpleResponse) Response() *Message

Constants

const (
	RespAccept   = SimpleResponse(accept)
	RespContinue = SimpleResponse(continue_)
	RespDiscard  = SimpleResponse(discard)
	RespReject   = SimpleResponse(reject)
	RespTempFail = SimpleResponse(tempFail)
)

Define standard responses with no data

const (
	// set which actions the milter wants to perform
	OptAddHeader    OptAction = 0x01
	OptChangeBody   OptAction = 0x02
	OptAddRcpt      OptAction = 0x04
	OptRemoveRcpt   OptAction = 0x08
	OptChangeHeader OptAction = 0x10
	OptQuarantine   OptAction = 0x20

	// mask out unwanted parts of the SMTP transaction
	OptAllParts   OptProtocol = 0x00
	OptNoConnect  OptProtocol = 0x01
	OptNoHelo     OptProtocol = 0x02
	OptNoMailFrom OptProtocol = 0x04
	OptNoRcptTo   OptProtocol = 0x08
	OptNoBody     OptProtocol = 0x10
	OptNoHeaders  OptProtocol = 0x20
	OptNoEOH      OptProtocol = 0x40
)

Functions

func Close

func Close() (err error)

Close server listener and wait worked process

func RunServer

func RunServer(server net.Listener, init MilterInit, handlers ...func(error)) error

RunServer provides a convenient way to start a milter server Handlers provide way to handle errors from panics With nil handlers panics not recovered

Types

type CustomResponse

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

CustomResponse is a response instance used by callback handlers to indicate how the milter should continue processing of current message

func NewResponse

func NewResponse(code byte, data []byte) *CustomResponse

NewResponse generates a new CustomResponse suitable for WritePacket

func NewResponseStr

func NewResponseStr(code byte, data string) *CustomResponse

NewResponseStr generates a new CustomResponse with string payload

func (*CustomResponse) Continue

func (c *CustomResponse) Continue() bool

Continue returns false if milter chain should be stopped, true otherwise

func (*CustomResponse) Response

func (c *CustomResponse) Response() *Message

Response returns message instance with data

type Message

type Message struct {
	Code byte
	Data []byte
}

Message represents a command sent from milter client

type Milter

type Milter interface {
	// Abort current filter checks. Expected response:  NONE
	// Resets internal state of milter program to before SMFIC_HELO, but keeps the connection open.
	Abort(m *Modifier)

	// Connect is called to provide SMTP connection data for incoming message
	//   supress with NoConnect
	Connect(host string, family string, port uint16, addr net.IP, m *Modifier) (Response, error)

	// Helo is called to process any HELO/EHLO related filters
	//   supress with NoHelo
	Helo(name string, m *Modifier) (Response, error)

	// MailFrom is called to process filters on envelope FROM address
	//   supress with NoMailForm
	MailFrom(from string, m *Modifier) (Response, error)

	// RcptTo is called to process filters on envelope TO address
	//   supress with NoRcptTo
	RcptTo(rcptTo string, m *Modifier) (Response, error)

	// Header is called once for each header in incoming message
	//   supress with NoHeaders
	Header(name string, value string, m *Modifier) (Response, error)

	// Headers is called when all message headers have been processed
	//   supress with NoHeaders
	Headers(h textproto.MIMEHeader, m *Modifier) (Response, error)

	// BodyChunk is called to process next message body chunk data (up to 64KB in size)
	//   supress with NoBody
	BodyChunk(chunk []byte, m *Modifier) (Response, error)

	// Body is called at the end of each message
	//   all changes to message's content & attributes must be done here
	Body(m *Modifier) (Response, error)

	// Close connection
	//
	Close(m *Modifier)
}

Milter is an interface for milter callback handlers

type MilterInit

type MilterInit func() (Milter, OptAction, OptProtocol)

MilterInit initializes milter options multiple options can be set using a bitmask

type Modifier

type Modifier struct {
	Macros  map[string]string
	Headers textproto.MIMEHeader
	// contains filtered or unexported fields
}

Modifier provides access to Macros, Headers and Body data to callback handlers. It also defines a number of functions that can be used by callback handlers to modify processing of the email message

func (*Modifier) AddHeader

func (m *Modifier) AddHeader(name, value string) error

AddHeader appends a new email message header the message

func (*Modifier) AddRecipient

func (m *Modifier) AddRecipient(r string) error

AddRecipient appends a new envelope recipient for current message

func (*Modifier) ChangeHeader

func (m *Modifier) ChangeHeader(index int, name, value string) error

ChangeHeader replaces the header at the specified position with a new one

func (*Modifier) DeleteRecipient

func (m *Modifier) DeleteRecipient(r string) error

DeleteRecipient removes an envelope recipient address from message

func (*Modifier) Quarantine

func (m *Modifier) Quarantine(reason string) error

Quarantine a message by giving a reason to hold it

func (*Modifier) ReplaceBody

func (m *Modifier) ReplaceBody(body []byte) error

ReplaceBody substitutes message body with provided body

type OptAction

type OptAction uint32

OptAction sets which actions the milter wants to perform. Multiple options can be set using a bitmask.

type OptProtocol

type OptProtocol uint32

OptProtocol masks out unwanted parts of the SMTP transaction. Multiple options can be set using a bitmask.

type Response

type Response interface {
	Response() *Message
	Continue() bool
}

Response represents a response structure returned by callback handlers to indicate how the milter server should proceed

type Server

type Server struct {
	Listener      net.Listener
	MilterFactory MilterInit
	ErrHandlers   []func(error)
	sync.WaitGroup
}

Milter server for handling and processing incoming connections support panic handling via ErrHandler couple of func(error) could be provided for handling error

func (*Server) Close

func (s *Server) Close() (err error)

For graceful shutdown Stop accepting new connections And wait until processing connections ends

func (*Server) RunServer

func (s *Server) RunServer() error

Start milter server via provided listener

type SimpleResponse

type SimpleResponse byte

SimpleResponse type to define list of pre-defined responses

func (SimpleResponse) Continue

func (r SimpleResponse) Continue() bool

Continue to process milter messages only if current code is Continue

func (SimpleResponse) Response

func (r SimpleResponse) Response() *Message

Response returns a Message object reference