output

Documentation

Overview

Package output is the collection of standard outputs for use with disdup. It mainly implements simple, reusable output components which can either be directly integrated into a user-facing application, or which can be used to form another, dissimilar component.

Index

• Constants
• Variables
• type Attachment
  • func (a *Attachment) Read(p []byte) (n int, err error)
• type Channel
  • func (c *Channel) Close() error
  • func (c *Channel) Open(s *discordgo.Session) error
  • func (c *Channel) Write(m Message)
• type MailServer
  • func (m MailServer) AddrInfo() (host string, port int, err error)
• type Mailer
  • func (m *Mailer) Close() error
  • func (m *Mailer) Open(s *discordgo.Session) error
  • func (m *Mailer) Write(msg Message)
• type Message
• type Output
• type RawChannel
  • func (r *RawChannel) Close() error
  • func (r *RawChannel) Open(s *discordgo.Session) error
  • func (r *RawChannel) Write(m Message)
• type Writer
  • func (w *Writer) Close() error
  • func (w *Writer) Open(s *discordgo.Session) error
  • func (w *Writer) Write(m Message)

Constants

const (
	// No messages are detected as replies.
	MailerReplyNone = iota
	// Only messages which were discord replies are replies.
	MailerReplyReplies
	// Messages by the same user in the same channel are replies.
	MailerReplyUser
	// Messages by any user in the same channel are replies.
	MailerReplyChannel
)

Reply detection modes. Modes are more broad the higher their number is, with MailerReplyChannel being the most broad and MailerReplyNone being the most restrictive. Use of unknown modes for the replies mode will cause a panic at initialization time.

const (
	MailerDefaultSubject = "[disdup] {author} in #{channel}"
	MailerDefaultFooter  = "This email was sent by Disdup. https://github.com/ethanv2/disdup"
)

Default configuration values for the output. Some values are set to these if they are their zero values at the time that Open is called.

const (
	// Collate messages sent in the same channel of the same guild together.
	WriterCollateChannel = iota + 1
	// Collate messages sent by the same user in the same channel together.
	WriterCollateUser
)

Collation modes for collecting together consecutive alike messages. Each larger mode includes all those below it. It is impossible to, for instance, collate users without collating channels. Unknown collation modes are ignored.

Constants are simply a linear sequence which we can test against inclusively using >= for a certain flag.

Variables

var (
	ErrChanTimeout = errors.New("output channel: timeout on send")
	ErrChanNil     = errors.New("output channel: nil output")
)

var (
	ErrBadServer      = errors.New("output mailer: invalid host format: expect hostname:port")
	ErrMailConnection = errors.New("output mailer: mail server connection")
)

Mailer initialization errors.

var (
	ErrNilOutput = errors.New("output writer: use with nil output")
	ErrNotOpen   = errors.New("output writer: write before open")
)

Writer error values.

Types

type Attachment

type Attachment struct {
	Filename, Type string
	Content        []byte
	// contains filtered or unexported fields
}

An Attachment is an attachment embedded in a message and downloaded beforehand. It should not be modified under any circumstances, as the slice points to the cached copy of the data.

func (*Attachment) Read

func (a *Attachment) Read(p []byte) (n int, err error)

Read reads content into buffer p up to len(p). Returns EOF once a.Content is exhausted. Not safe for concurrent use, as an internal read head offset is used.

type Channel

type Channel struct {
	Output  chan string
	Timeout time.Duration
}

Channel outputs formatted messages to a channel, optionally with a timeout. Channel closes its output channel once the output is closed.

If channel is nil, Channel.Open will return an error. If Timeout is zero, no timeout is enforced.

func (*Channel) Close

func (c *Channel) Close() error

func (*Channel) Open

func (c *Channel) Open(s *discordgo.Session) error

func (*Channel) Write

func (c *Channel) Write(m Message)

type MailServer

type MailServer struct {
	// Full server address, in the format hostname:port
	Address  string
	Username string
	Password string
}

A MailServer is the basic configuration for an SMTP server connection. Minimal details are supplied, which are the minimum required to connect to most servers.

func (MailServer) AddrInfo

func (m MailServer) AddrInfo() (host string, port int, err error)

AddrInfo parses the host and port from the supplied address.

type Mailer

type Mailer struct {
	// To whom shall we send this email? This is the full email address,
	// including domain and/or port numbers.
	To string
	// From whom shall this email be sent? This is the full email address
	// which will appear in the From field.
	From string
	// A format string for the message. If empty, MailerDefaultSubject is
	// used. If a message is a reply via the rules specified, "Re: " is
	// prepended to the subject.
	// Format options are as follows:
	//  - {id}: the message snowflake id
	//  - {author}: the username (user#tag) author of the message
	//  - {guild}: the server name in which the message was sent
	//  - {guild_id}: the server id in which the message was sent
	//  - {channel}: the channel name in which the message was sent
	//  - {channel_id}: the channel id in which the message was sent
	//  - {time}: the message timestamp, formatted in standard email format
	SubjectFormat string
	// What messages shall be detected as replies and under which
	// circumstances? See associated constants for details.
	ReplyMode uint
	// Custom headers to attach to the email message.
	CustomHeaders map[string]string
	// Custom text to prepend to the beginning of the message body.
	Preamble string
	// Custom text to append to the end of the message body after a
	// separating line.
	Footer string
	// SMTP server and authentication settings.
	Server MailServer
	// contains filtered or unexported fields
}

Mailer outputs messages by sending an email message to a recipient. Emails can be configured with certain headers, specific handling for attachments and modes for collation into threads.

For some features of Mailer to work correctly, an internal state must be maintained. As a result, a Mailer can only be used serially. This is handled internally and all Mailer methods are safe for concurrent use.

func (*Mailer) Close

func (m *Mailer) Close() error

func (*Mailer) Open

func (m *Mailer) Open(s *discordgo.Session) error

func (*Mailer) Write

func (m *Mailer) Write(msg Message)

Write formats the incoming message for email and then hands off to the sender to send to the server.

type Message

type Message struct {
	*discordgo.Message
	PrettyContent string
	ChannelName   string
	GuildName     string
	Downloads     []Attachment
}

A Message is a superset of the discord message object with extra information retrieved and managed by disdup. Although messages are passed to outputs by reference, it should be assumed that they are immutable.

type Output

type Output interface {
	Open(s *discordgo.Session) error
	Write(m Message)
	Close() error
}

An Output is a destination for messages from Disdup. It has a very similar interface to os.File and io.ReadCloser, mainly for familiarity with existing APIs.

Open is called at duplicator startup once. It is called concurrently with other outputs, so it may not duplicate state. It is responsible for initialising the state of the output. If error returned is not nil, disdup startup is aborted and the error is propagated to the client.

Write is called whenever a matching incoming message event is received. For more information on available information, see the documentation for the Message struct. You are free to do any operation in Write, but it is best not to block for too long. as no new message events can be processed until all outputs for the current one have completed.

Close is called exactly once upon the dropping of the output by disdup. If it throws an error, the rest of the close callbacks will be called before the error is propagated to the client code.

type RawChannel

type RawChannel struct {
	Output  chan Message
	Timeout time.Duration
}

RawChannel outputs a raw message object to the given channel, optionally with a timeout. Channel closes its output channel once the output is closed.

If channel is nil, Channel.Open will return an error. If TImeout is zero, no timeout is enforced.

func (*RawChannel) Close

func (r *RawChannel) Close() error

func (*RawChannel) Open

func (r *RawChannel) Open(s *discordgo.Session) error

func (*RawChannel) Write

func (r *RawChannel) Write(m Message)

type Writer

type Writer struct {
	Output io.WriteCloser
	// Prefix will be prepended to each message log.
	Prefix string
	// Collate mode. See constants for documentation.
	Collate int
	// contains filtered or unexported fields
}

Writer outputs messages to an io.Writer, formatted with a timestamp, author and channel name.

If collate is non-zero, it is a bitwise combination of one or more collation flags. See collation flags documentation for use.

func (*Writer) Close

func (w *Writer) Close() error

func (*Writer) Open

func (w *Writer) Open(s *discordgo.Session) error

func (*Writer) Write

func (w *Writer) Write(m Message)