// Package pop3 implements parts relevant to clients
// of the POP3 protocol as specified by RFC 1939.
//
// Package pop3 is designed to be used in a TLS >=1.2 environment. Cf. RFC 8314, cf. RFC 8997.
//
// POP3 defines three states: AUTHORIZATION, TRANSACTION and UPDATE.
// This package is written in a way that
// connection acquisition means having passed AUTHORIZATION,
// connection utilisation happens in TRANSACTION and
// (*Conn).Close means sending QUIT, going into UPDATE and ending the connection.
//
// For registered POP3 extensions, cf. https://www.iana.org/assignments/pop3-extension-mechanism/pop3-extension-mechanism.xml
//
// TODO(jfrech): 2023-09-14: Package pop3 does not assume the presence of CAPA (cf. https://datatracker.ietf.org/doc/html/rfc2449#section-5)
//
// TODO(jfrech): 2023-09-14: I am not quite sure if "+OK text" leads to a head of " text" or "  text". How else should one handle "+OKtext" or "+OK  text"?
//
// Written by Jonathan Frech, 2022--2023.
package pop3

// A keyword should be uppercase, three or four characters and only consist of
// ASCII printables (character code ' ' < . <= '~'). Cf. RFC 1939 3.
type Keyword string

// POP3 keywords
const (
    // Cf. RFC 1939
    // AUTHORIZATION state's QUIT is ignored

    // Cf. RFC 1939
    STAT = Keyword("STAT")
    LIST = Keyword("LIST") // TODO not yet implemented
    RETR = Keyword("RETR") // retrieve
    DELE = Keyword("DELE") // delete
    NOOP = Keyword("NOOP") // no-operation
    RSET = Keyword("RSET") // TODO not yet implemented

    // Cf. RFC 1939
    QUIT = Keyword("QUIT")

    // Cf. RFC 1939
    TOP = Keyword("TOP") // TODO not yet implemented
    UIDL = Keyword("UIDL")
    USER = Keyword("USER")
    PASS = Keyword("PASS") // password
    // APOP is ignored

    // Cf. RFC 2449
    CAPA = Keyword("CAPA") // capabilities

    // Cf. RFC 2595 4.
    STLS = Keyword("STLS") // start TLS
)

// MaximumPhysicalLineLength includes in its count both status indicators
// ("+OK" or "-ERR"), byte-stuffing (dot-encoding: ".dot." for "dot.") and
// trailing CRLF.
//
// Currently, this limit is not enforced but merely used as an initial buffer
// capacity.
//
// RFC 1939 3. specifies the maximum response length to be 512 bytes.
// RFC 822 3.4.8. very cautiously discourages mail message header lines longer
// than around a hundred bytes.
// RFC 2822 2.1.1. recommends mail message lines be no longer than 80 bytes
// and forbids lines longer than 1000 bytes.
// RFC 5322 2.1.1. repeats the above.
const MaximumPhysicalLineLength = 512

// POP3 status indicators
const (
    PlusOK = "+OK"
    MinusERR = "-ERR"
)