nntp

README

nntp.go

An NNTP (news) Client package for go (golang). Forked from nntp-go and forked again from chrisfarms/nntp.

This fork contains support for:

• Parsing broken overview responses
• XOVER (attempted automatically when OVER fails)
• XZVER (compressed headers, Astraweb style)
• XFEATURE COMPRESS GZIP (compressed headers, Giganews style)

Example

	// connect to news server
	conn, err := nntp.Dial("tcp", "news.example.com:119")
	if err != nil {
		log.Fatalf("connection failed: %v", err)
	}

	// auth
	if err := conn.Authenticate("user", "pass"); err != nil {
		log.Fatalf("Could not authenticate")
	}

	// connect to a news group
	grp := "alt.binaries.pictures"
	_, l, _, err := conn.Group(grp)
	if err != nil {
		log.Fatalf("Could not connect to group %s: %v %d", grp, err, l)
	}

	// fetch an article
	id := "<4c1c18ec$0$8490$c3e8da3@news.astraweb.com>"
	article, err := conn.Article(id)
	if err != nil {
		log.Fatalf("Could not fetch article %s: %v", id, err)
	}

	// read the article contents
	body, err := ioutil.ReadAll(article.Body)
	if err != nil {
		log.Fatalf("error reading reader: %v", err)
	}

Documentation

Overview

RFC5322 date parsing. Copied from net/mail Go standard library package.

The nntp package implements a client for the news protocol NNTP, as defined in RFC 3977.

Index

• func ErrorCode(err error) uint
• func IsProtocol(err error) bool
• type Article
  • func (a *Article) String() string
  • func (a *Article) WriteTo(w io.Writer) (int64, error)
• type Conn
  • func Dial(network, addr string) (*Conn, error)
  • func DialTLS(network, addr string, config *tls.Config) (*Conn, error)
  • func (c *Conn) Article(id string) (*Article, error)
  • func (c *Conn) ArticleText(id string) (io.Reader, error)
  • func (c *Conn) Authenticate(username, password string) error
  • func (c *Conn) Body(id string) (io.Reader, error)
  • func (c *Conn) Capabilities() ([]string, error)
  • func (c *Conn) Date() (time.Time, error)
  • func (c *Conn) EnableCompression() error
  • func (c *Conn) Group(group string) (status *Group, err error)
  • func (c *Conn) Head(id string) (*Article, error)
  • func (c *Conn) HeadText(id string) (io.Reader, error)
  • func (c *Conn) Help() (io.Reader, error)
  • func (c *Conn) Last() (number, msgid string, err error)
  • func (c *Conn) List(a ...string) ([]*Group, error)
  • func (c *Conn) ListExtensions() ([]string, error)
  • func (c *Conn) ListGroup(group string, from, to int64) (listing *GroupListing, err error)
  • func (c *Conn) ModeReader() error
  • func (c *Conn) NewGroups(since time.Time) ([]*Group, error)
  • func (c *Conn) NewNews(group string, since time.Time) ([]string, error)
  • func (c *Conn) Next() (number, msgid string, err error)
  • func (c *Conn) Overview(begin, end int64) ([]MessageOverview, error)
  • func (c *Conn) Post(a *Article) error
  • func (c *Conn) Quit() error
  • func (c *Conn) RawPost(r io.Reader) error
  • func (c *Conn) Stat(id string) (number, msgid string, err error)
  • func (c *Conn) Trace(c2s, s2c io.Writer)
• type Error
  • func (e Error) Error() string
• type Group
• type GroupListing
• type MessageOverview
• type ProtocolError
  • func (p ProtocolError) Error() string

Functions

func ErrorCode

func ErrorCode(err error) uint

func IsProtocol

func IsProtocol(err error) bool

Types

type Article

type Article struct {
	Header map[string][]string
	Body   io.Reader
}

An Article represents an NNTP article.

func (*Article) String

func (a *Article) String() string

func (*Article) WriteTo

func (a *Article) WriteTo(w io.Writer) (int64, error)

type Conn

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

A Conn represents a connection to an NNTP server. The connection with an NNTP server is stateful; it keeps track of what group you have selected, if any, and (if you have a group selected) which article is current, next, or previous.

Some methods that return information about a specific message take either a message-id, which is global across all NNTP servers, groups, and messages, or a message-number, which is an integer number that is local to the NNTP session and currently selected group.

For all methods that return an io.Reader (or an *Article, which contains an io.Reader), that io.Reader is only valid until the next call to a method of Conn.

func Dial

func Dial(network, addr string) (*Conn, error)

Dial connects to an NNTP server. The network and addr are passed to net.Dial to make the connection.

Example:

conn, err := nntp.Dial("tcp", "my.news:nntp")

func DialTLS

func DialTLS(network, addr string, config *tls.Config) (*Conn, error)

Same as Dial but handles TLS connections

func (*Conn) Article

func (c *Conn) Article(id string) (*Article, error)

Article returns the article named by id as an *Article.

func (*Conn) ArticleText

func (c *Conn) ArticleText(id string) (io.Reader, error)

ArticleText returns the article named by id as an io.Reader. The article is in plain text format, not NNTP wire format.

func (*Conn) Authenticate

func (c *Conn) Authenticate(username, password string) error

Authenticate logs in to the NNTP server. It only sends the password if the server requires one.

func (*Conn) Body

func (c *Conn) Body(id string) (io.Reader, error)

Body returns the body for the article named by id as an io.Reader.

func (*Conn) Capabilities

func (c *Conn) Capabilities() ([]string, error)

Capabilities returns a list of features this server performs. Not all servers support capabilities.

func (*Conn) Date

func (c *Conn) Date() (time.Time, error)

Date returns the current time on the server. Typically the time is later passed to NewGroups or NewNews.

func (*Conn) EnableCompression

func (c *Conn) EnableCompression() error

Attempt to enable connection-level compression, e.g. XFEATURE COMPRESS GZIP. This will fail with an nntp.Error if the server doesn't support it, or some other type of error in case something more severe has occurred.

func (*Conn) Group

func (c *Conn) Group(group string) (status *Group, err error)

Group changes the current group.

func (*Conn) Head

func (c *Conn) Head(id string) (*Article, error)

Head returns the header for the article named by id as an *Article. The Body field in the Article is nil.

func (*Conn) HeadText

func (c *Conn) HeadText(id string) (io.Reader, error)

HeadText returns the header for the article named by id as an io.Reader. The article is in plain text format, not NNTP wire format.

func (*Conn) Help

func (c *Conn) Help() (io.Reader, error)

Help returns the server's help text.

func (*Conn) Last

func (c *Conn) Last() (number, msgid string, err error)

Last selects the previous article, returning its message number and id.

func (*Conn) List

func (c *Conn) List(a ...string) ([]*Group, error)

List returns a list of groups present on the server. Valid forms are:

List() - return active groups
List(keyword) - return different kinds of information about groups
List(keyword, pattern) - filter groups against a glob-like pattern called a wildmat

func (*Conn) ListExtensions

func (c *Conn) ListExtensions() ([]string, error)

func (*Conn) ListGroup

func (c *Conn) ListGroup(group string, from, to int64) (listing *GroupListing, err error)

ListGroup changes the current group.

func (*Conn) ModeReader

func (c *Conn) ModeReader() error

ModeReader switches the NNTP server to "reader" mode, if it is a mode-switching server.

func (*Conn) NewGroups

func (c *Conn) NewGroups(since time.Time) ([]*Group, error)

NewGroups returns a list of groups added since the given time.

func (*Conn) NewNews

func (c *Conn) NewNews(group string, since time.Time) ([]string, error)

NewNews returns a list of the IDs of articles posted to the given group since the given time.

func (*Conn) Next

func (c *Conn) Next() (number, msgid string, err error)

Next selects the next article, returning its message number and id.

func (*Conn) Overview

func (c *Conn) Overview(begin, end int64) ([]MessageOverview, error)

Overview returns overviews of all messages in the current group with message number between begin and end, inclusive.

func (*Conn) Post

func (c *Conn) Post(a *Article) error

Post posts an article to the server.

func (*Conn) Quit

func (c *Conn) Quit() error

Quit sends the QUIT command and closes the connection to the server.

func (*Conn) RawPost

func (c *Conn) RawPost(r io.Reader) error

RawPost reads a text-formatted article from r and posts it to the server.

func (*Conn) Stat

func (c *Conn) Stat(id string) (number, msgid string, err error)

Stat looks up the message with the given id and returns its message number in the current group, and vice versa. The returned message number can be "0" if the current group isn't one of the groups the message was posted to.

func (*Conn) Trace

func (c *Conn) Trace(c2s, s2c io.Writer)

Enables tracing, such that future IO gets dumped to the indicated writers, replacing any current tracing configuration.

This discards the contents of the current server-to-client receive buffer and should therefore not be attempted while any commands are in progress.

type Error

type Error struct {
	Code uint
	Msg  string
}

An Error represents an error response from an NNTP server.

func (Error) Error

func (e Error) Error() string

type Group

type Group struct {
	Name string
	// Count of messages in the group
	Count int64
	// High and low message-numbers
	High, Low int64
	// Status indicates if general posting is allowed --
	// typical values are "y", "n", or "m".
	Status string
}

A Group gives information about a single news group on the server.

type GroupListing

type GroupListing struct {
	Group
	Articles []int64
}

type MessageOverview

type MessageOverview struct {
	MessageNumber int64     // Message number in the group
	Subject       string    // Subject header value. Empty if the header is missing.
	From          string    // From header value. Empty is the header is missing.
	Date          time.Time // Parsed Date header value. Zero if the header is missing or unparseable.
	MessageId     string    // Message-Id header value. Empty is the header is missing.
	References    []string  // Message-Id's of referenced messages (References header value, split on spaces). Empty if the header is missing.
	Bytes         int       // Message size in bytes, called :bytes metadata item in RFC3977.
	Lines         int       // Message size in lines, called :lines metadata item in RFC3977.
	Extra         []string  // Any additional fields returned by the server.
}

Overview of a message returned by OVER command.

type ProtocolError

type ProtocolError string

A ProtocolError represents responses from an NNTP server that seem incorrect for NNTP.

func (ProtocolError) Error

func (p ProtocolError) Error() string