rspamd

README

go-rspamd

Introduction

go-rspamd is a client library written to help interact with a rspamd instance, via HTTP. go-rspamd facilitates

• Content scanning of emails
• Training rspamd's Bayesian classifier
• Updating rspamd's fuzzy storage by adding or removing messages
• Analyzing content scanning results

Refer to rspamd documentation for help configuring and setting up rspamd.

Usage

The API is defined here.

The client helps send emails to all POST endpoints on rspamd. Support for all GET endpoints does not currently exist as they can be accessed through rspamd's web interface, although support may exist in the future. A full list of all endpoints can be found here.

The client supports email formats that implement io.Reader or io.WriterTo. For example, this means that clients can pass in both gomail.Message objects, which implement io.WriteTo or simply the contents of an .eml file, which implement io.Reader. gomail can be found here.

Examples

Note: go-rspamd is geared towards clients that use context. However if you don't, whenever context.Context is expected, you can use context.Background().

Import go-rspamd:

import "github.com/Shopify/go-rspamd"

Instantiate the client with the url of your rspamd instance:

 client := rspamd.New("https://contentscanner.com")

Optionally pass in credentials:

 client := rspamd.New("https://contentscanner.com", rspamd.Credentials("username", "password"))

Ping your rspamd instance:

pong, _ := client.Ping(ctx)

Scan an email from an io.Reader (eg. loading an .eml file):

f, _ := os.Open("/path/to/email")
email := rspamd.NewEmailFromReader(f).QueueId(2)
checkRes, _ := client.Check(ctx, email)

Scan an email from an io.WriteTo (eg. a gomail Message):

// let mail be of type *gomail.Message
// attach a Queue-Id to rspamd.Email instance
email := rspamd.NewEmailFromWriterTo(mail).QueueID(1)
checkRes, _ := client.Check(ctx, email)

Add a message to fuzzy storage, attaching a flag and weight as per docs:

// let mail be of type *gomail.Message
email := rspamd.NewEmailFromWriterTo(mail).QueueID(2).Flag(1).Weight(19)
learnRes, _ := client.FuzzyAdd(ctx, email)

Semantics

Contributing

We invite contributions to extend the API coverage.

Report a bug: Open an issue
Fix a bug: Open a pull request

Versioning

go-rspamd respects the Semantic Versioning for major/minor/patch versions.

License

MIT

Documentation

Index

• func IsAlreadyLearnedError(err error) bool
• func IsNotFound(err error) bool
• func New(url string, options ...Option) *client
• func NewMock() *mockClient
• type CheckResponse
• type Client
• type Email
  • func NewEmailFromReader(message io.Reader) *Email
  • func NewEmailFromWriterTo(message io.WriterTo) *Email
  • func (e *Email) Flag(flag int) *Email
  • func (e *Email) QueueID(queueID string) *Email
  • func (e *Email) Weight(weight float64) *Email
• type LearnResponse
• type Option
  • func Credentials(username string, password string) Option
• type Options
• type PingResponse
• type SymbolData
• type UnexpectedResponseError
  • func (e *UnexpectedResponseError) Error() string

Functions

func IsAlreadyLearnedError

func IsAlreadyLearnedError(err error) bool

IsAlreadyLearnedError returns true if a request returns 208, which can happen if rspamd detects a message has already been learned as SPAM/HAM. This can allow clients to gracefully handle this use case.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns true if a request returned a 404. This helps discern a known issue with rspamd's /checkv2 endpoint.

func New

func New(url string, options ...Option) *client

New returns a client. It takes the url of a rspamd instance, and configures the client with Options which are closures.

func NewMock

func NewMock() *mockClient

NewMock creates a mock client, which can be used wherever client is used, to test/

Types

type CheckResponse

type CheckResponse struct {
	Score     float64               `json:"score"`
	MessageID string                `json:"message-id"`
	Symbols   map[string]SymbolData `json:"symbols"`
}

CheckResponse encapsulates the response of Check.

type Client

type Client interface {
	Check(context.Context, *Email) (*CheckResponse, error)
	LearnSpam(context.Context, *Email) (*LearnResponse, error)
	LearnHam(context.Context, *Email) (*LearnResponse, error)
	FuzzyAdd(context.Context, *Email) (*LearnResponse, error)
	FuzzyDel(context.Context, *Email) (*LearnResponse, error)
	Ping(context.Context) (PingResponse, error)
}

Client is a rspamd HTTP client.

type Email

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

Email represents an abstract type holding the email content and headers to pass to rspamd.

func NewEmailFromReader

func NewEmailFromReader(message io.Reader) *Email

NewEmailFromWriterTo creates an Email instance from an io.Reader.

func NewEmailFromWriterTo

func NewEmailFromWriterTo(message io.WriterTo) *Email

NewEmailFromWriterTo creates an Email instance from an io.WriterTo.

func (*Email) Flag

func (e *Email) Flag(flag int) *Email

Flag attaches a flag to an Email, and eventually as a header when sent to rspamd. Flag identifies fuzzy storage.

func (*Email) QueueID

func (e *Email) QueueID(queueID string) *Email

QueueID attaches a queue-id to an Email, and eventually as a header when sent to rspamd. This header helps clients with rspamd logging.

func (*Email) Weight

func (e *Email) Weight(weight float64) *Email

Weight attaches a weight to an Email, and eventually as a header when sent to rspamd. Weight is added to hashes.

type LearnResponse

type LearnResponse struct {
	Success bool `json:"success"`
}

LearnResponse encapsulates the response of LearnSpam, LearnHam, FuzzyAdd, FuzzyDel.

type Option

type Option func(*client) error

Option is a function that configures the rspamd client.

func Credentials

func Credentials(username string, password string) Option

Credentials sets the credentials passed in parameters. It returns an Option which is used to configure the client.

type Options

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

Options encapsulate headers the client can pass in requests to rspamd.

type PingResponse

type PingResponse string

PingResponse encapsulates the response of Ping.

type SymbolData

type SymbolData struct {
	Name        string  `json:"name"`
	Score       float64 `json:"score"`
	MetricScore float64 `json:"metric_score"`
	Description string  `json:"description"`
}

SymbolData encapsulates the data returned for each symbol from Check.

type UnexpectedResponseError

type UnexpectedResponseError struct {
	Status int
}

func (*UnexpectedResponseError) Error

func (e *UnexpectedResponseError) Error() string