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

• Constants
• func IsAlreadyLearnedError(err error) bool
• func IsNotFound(err error) bool
• func New(url string, options ...Option) *client
• func NewFromClient(restyClient *resty.Client) *client
• func NewMock() *mockClient
• func ReaderFromWriterTo(writerTo io.WriterTo) io.Reader
• func SetFlag(header http.Header, flag int)
• func SetQueueID(header http.Header, queueID string)
• func SetWeight(header http.Header, weight int)
• type CheckRequest
• type CheckResponse
• type Client
• type FuzzyRequest
• type FuzzyResponse
• type LearnRequest
• type LearnResponse
• type Option
  • func Credentials(username string, password string) Option
• type PingResponse
• type SymbolData
• type UnexpectedResponseError
  • func (e *UnexpectedResponseError) Error() string

Constants

const (
	QueueID = "Queue-Id"
	Flag    = "Flag"
	Weight  = "Weight"
)

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 NewFromClient

func NewFromClient(restyClient *resty.Client) *client

NewFromClient returns a client. It takes an instance of resty.Client.

func NewMock

func NewMock() *mockClient

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

func ReaderFromWriterTo

func ReaderFromWriterTo(writerTo io.WriterTo) io.Reader

func SetFlag

func SetFlag(header http.Header, flag int)

func SetQueueID

func SetQueueID(header http.Header, queueID string)

func SetWeight

func SetWeight(header http.Header, weight int)

Types

type CheckRequest

type CheckRequest struct {
	Message io.Reader
	Header  http.Header
}

CheckRequest encapsulates the request of Check.

type CheckResponse

type CheckResponse struct {
	Score     float64               `json:"score"`
	Action    string                `json:"action"`
	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, *CheckRequest) (*CheckResponse, error)
	LearnSpam(context.Context, *LearnRequest) (*LearnResponse, error)
	LearnHam(context.Context, *LearnRequest) (*LearnResponse, error)
	FuzzyAdd(context.Context, *FuzzyRequest) (*FuzzyResponse, error)
	FuzzyDel(context.Context, *FuzzyRequest) (*FuzzyResponse, error)
	Ping(context.Context) (PingResponse, error)
}

Client is a rspamd HTTP client.

type FuzzyRequest

type FuzzyRequest struct {
	Message io.Reader
	Flag    int
	Weight  int
	Header  http.Header
}

FuzzyRequest encapsulates the request of FuzzyAdd, FuzzyDel.

type FuzzyResponse

type FuzzyResponse struct {
	Success bool     `json:"success"`
	Hashes  []string `json:"hashes"`
}

FuzzyResponse encapsulates the response of FuzzyAdd, FuzzyDel.

type LearnRequest

type LearnRequest struct {
	Message io.Reader
	Header  http.Header
}

LearnRequest encapsulates the request of LearnSpam, LearnHam.

type LearnResponse

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

LearnResponse encapsulates the response of LearnSpam, LearnHam.

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 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