README
¶
nntpclient
This package provides a simple NNTP client that conforms to RFC 3977. It also supports the following extensions:
TODO
Documentation
¶
Index ¶
- Variables
- func AuthError(code int, message string) error
- func ReadBody(reader MultibyteReader, writer io.Writer) error
- func ReadHeaders(reader MultibyteReader) (textproto.MIMEHeader, int, error)
- func UnexpectedError(code int, message string) error
- type Capabilities
- type Client
- func (c *Client) Article(id string, writer io.Writer) (textproto.MIMEHeader, error)
- func (c *Client) ArticleAsBytes(id string) (textproto.MIMEHeader, []byte, error)
- func (c *Client) Authenticate(user string, pass string) error
- func (c *Client) Body(id string, writer io.Writer) error
- func (c *Client) BodyAsBytes(id string) ([]byte, error)
- func (c *Client) Capabilities() (*Capabilities, error)
- func (c *Client) Close() error
- func (c *Client) Connect() error
- func (c *Client) Date() (time.Time, error)
- func (c *Client) Group(name string) (*GroupSummary, error)
- func (c *Client) Head(id string) (textproto.MIMEHeader, error)
- func (c *Client) Help() (string, error)
- func (c *Client) Last() error
- func (c *Client) ListActive(wildmat string) (map[string]ListGroup, error)
- func (c *Client) ListActiveTimes(wildmat string) (map[string]ListGroupTimes, error)
- func (c *Client) ListDistribPats() ([]ListDistribPattern, error)
- func (c *Client) ListGroup(name string) (*GroupList, error)
- func (c *Client) ListNewsgroups(wildmat string) (map[string]ListNewsgroup, error)
- func (c *Client) ModeReader() error
- func (c *Client) NewGroups(since time.Time) (map[string]ListGroup, error)
- func (c *Client) NewNews(wildmat string, since time.Time) ([]string, error)
- func (c *Client) Next() error
- func (c *Client) Quit() error
- func (c *Client) StartTLS(config *tls.Config) error
- func (c *Client) Stat(id string) (int, string, error)
- type GroupList
- type GroupSummary
- type ListDistribPattern
- type ListGroup
- type ListGroupTimes
- type ListNewsgroup
- type MultibyteReader
- type Option
- type Response
Constants ¶
This section is empty.
Variables ¶
var ErrCurrentArticleNumInvalid = fmt.Errorf("current article number is invalid: %w", NntpError)
var ErrNoArticleWithId = fmt.Errorf("no article with that message-id: %w", NntpError)
var ErrNoArticleWithNum = fmt.Errorf("no article with that number: %w", NntpError)
var ErrNoGroupSelected = fmt.Errorf("no newsgroup selected: %w", NntpError)
var ErrNoNextArticle = fmt.Errorf("no next article in this group: %w", NntpError)
var ErrNoPrevArticle = fmt.Errorf("no previous article in this group: %w", NntpError)
var ErrNoSuchGroup = fmt.Errorf("no such newsgroup found: %w", NntpError)
var ErrUnexpectedEOF = fmt.Errorf("unexpected end of response: %w", NntpError)
var NntpError = errors.New("nntp error")
NntpError is the base error for all errors that derive from issuing commands to the server. Any such errors can be checked with errors.Is.
Functions ¶
func ReadBody ¶
func ReadBody(reader MultibyteReader, writer io.Writer) error
ReadBody is used to read a body, or body-like, block of bytes provided by the passed in reader. The body is not processed in any way, but is instead written to the supplied writer. This allows for processing of bodies according to their content by a client. Reading stops when the termination line (`.\r\n`) is encountered.
If an end of file is encountered before the termination line, the io.EOF error will be returned. In this case, it is not advisable to trust the bytes written to the writer.
func ReadHeaders ¶
func ReadHeaders(reader MultibyteReader) (textproto.MIMEHeader, int, error)
ReadHeaders parses a set of bytes with the expectation that they start with what look like header lines terminated by either an empty line, in the case of a header block at the top of an article, or the message termination line (`.\r\n`) as when reading a `HEAD` command response.
The result of this method, in the success case, is a map of headers and an integer representing the offset of the last read byte, e.g. the start of the body in an article. Otherwise, and error is returned and the other values may be incomplete or incorrect.
If an end of file is reached before a header block termination line then the io.EOF error will be returned along with the last read offset.
func UnexpectedError ¶
Types ¶
type Capabilities ¶
Capabilities is a map of all capability labels to the label's possible arguments. For example, the `COMPRESS` label may have a list of possible arguments that looks like `[DEFLATE]`.
type Client ¶
type Client struct {
// CanPost indicates if the server will allow the client to post articles.
// Useful in the future when posting is supported by the client.
CanPost bool
// contains filtered or unexported fields
}
Client is a simple [NNTP](https://datatracker.ietf.org/doc/html/rfc3977) client. Client instances should be created with New, NewTls, or NewWithPort (this one being the most flexible).
func New ¶
New creates a new Client instance that connects to the given `host` according to the given options. Instances created with this method will _always_ try to connect on port 119. Thus, it is not compatible with the WithTlsConfig options.
func NewTls ¶
NewTls creates a new Client instance that connects to the given `host` on port 563 utilizing a basic TLS configuration that sets the `ServerName` option to `host`. This should be good enough for most standard NNTP servers that support TLS on the standard port.
func NewWithPort ¶
NewWithPort is the most generic method for creating a new Client instance. It supports all options and allows flexibility in defining the destination port. If no TLS configuration is provided, via WithTlsConfig, then the connection will be in plain text.
func (*Client) Article ¶
Article gets an article from the server. The id parameter may be any of:
1. empty string (`""`) -- retrieve the "next" or "last" selected article 2. group article id -- the internal group article id, e.g. `1` 3. global id -- the global id for an article with brackets, e.g. `<foo.bar>`
Note, when using the global id it is not necessary to select a group first. But when using an internal group id, or the empty string, a group must be selected prior to invoking this function.
After reading the body of the article into the given writer, the headers will be returned if an error did not occur. If an error does occur, whatever part of the article body was read, if any, will have been written to the writer, nil will be returned for the headers, and the error will be returned.
func (*Client) ArticleAsBytes ¶
ArticleAsBytes is a wrapper for [Article] that reads the whole article into a buffer before returning the headers and the body of the article as a slice of bytes.
func (*Client) Authenticate ¶
Authenticate provides simple username and password authentication through the AUTHINFO extension (RFC 4643). The absence of an error indicates successful authentication.
func (*Client) Body ¶
Body is used to retrieve only the body of an article. As the article is read from the connection it is written to writer. The id parameter is handled in the same way as it is by [Article].
func (*Client) BodyAsBytes ¶
BodyAsBytes is used to retrieve only the body of an article as a slice of bytes. The full body is read into the slice before it is returned. The id parameter is handled in the same way as it is by [Article].
func (*Client) Capabilities ¶
func (c *Client) Capabilities() (*Capabilities, error)
Capabilities gets a mapping of all supported labels to their possible arguments.
func (*Client) Connect ¶
Connect establishes a connection to the server. This method must be invoked once prior to any command methods.
func (*Client) Group ¶
func (c *Client) Group(name string) (*GroupSummary, error)
Group selects a group and returns the summary for that group.
func (*Client) Head ¶
func (c *Client) Head(id string) (textproto.MIMEHeader, error)
Head retrieves only the headers for an article. The id parameter is handled in the same way as it is in [Article].
func (*Client) Last ¶
Last sets the selected article to the most recent article in the selected group.
func (*Client) ListActive ¶
ListActive retrieves a list of active groups. The wildmat parameter can be the empty string to indicate "all groups."
func (*Client) ListActiveTimes ¶
func (c *Client) ListActiveTimes(wildmat string) (map[string]ListGroupTimes, error)
ListActiveTimes retrieves a list of groups, when they were created, and by whom. The wildmat parameter can be the empty string to indicate "all groups."
func (*Client) ListDistribPats ¶
func (c *Client) ListDistribPats() ([]ListDistribPattern, error)
ListDistribPats retrieves a list of distribution header patterns supported by the server.
func (*Client) ListGroup ¶
ListGroup selects a group and returns a summary for the group along with a list of the group local article identifiers.
func (*Client) ListNewsgroups ¶
func (c *Client) ListNewsgroups(wildmat string) (map[string]ListNewsgroup, error)
ListNewsgroups retrieves a list of newsgroups known by the server. The wildmat parameter can be the empty string to indicate "all groups". The result is a map of group names to group names and group descriptions.
func (*Client) ModeReader ¶
ModeReader toggles the connection mode to "reader".
func (*Client) NewGroups ¶
NewGroups queries the server for the list of groups that have been added since a given time. If the location of that time is _not_ UTC, then only the date and time fields will be sent, leaving the interpretation of that time up to the server. If the location is set to UTC, then the GMT parameter is included in the query to the server.
func (*Client) NewNews ¶
NewNews queries the server for a list of new articles in groups matching the given wildmat since the given time. As with [NewGroups], the GMT parameter is dependent upon the since time being set to UTC.
func (*Client) Quit ¶
Quit sends a standard `QUIT` to the remote server and terminates the connection.
func (*Client) StartTLS ¶
StartTLS upgrades the current connection to a TLS protected one. See RFC 4642.
Note: if a config is not provided, one with the `ServerName` set to the host will be used.
func (*Client) Stat ¶
Stat is used to determine if an article exists. It works like [Article] in that the id may be the empty string, an internal group id, or a global message id.
If the article exists, its internal group id and global message id is returned. Otherwise, an error is returned along with `-1` and an empty string.
type GroupList ¶
type GroupList struct {
GroupSummary
ArticleNumbers []int
}
GroupList represents the details about a group along with the group local id numbers for the articles in the group.
type GroupSummary ¶
GroupSummary represents the details about a group.
type ListDistribPattern ¶
ListDistribPattern represents distribution header values supported by the server. See RFC 3977 §7.6.5.
type ListGroup ¶
ListGroup represents a group information line from a list directive. See RFC 3977 §7.6.3.
type ListGroupTimes ¶
ListGroupTimes represents a group information line from a `active.times` command. See RFC 3977 §7.6.4.
type ListNewsgroup ¶
ListNewsgroup represents a newsgroup information line from a `list newsgroups` directive. See RFC 3977 §7.6.6.
type MultibyteReader ¶
MultibyteReader is an interface for readers that support reading multiple bytes up to a delimiter in one read. See bufio.Reader.
type Option ¶
type Option func(client *Client)
func WithDialer ¶
WithDialer allows defining the dialer that will be used to establish the connection with the remote server.
func WithLogger ¶
WithLogger allows defining the logger instance that will be used when logging messages. The default logger logs at the "info" level to the stdout stream.
func WithTlsConfig ¶
WithTlsConfig allows defining the TLS configuration to be used when establishing a connection to a TLS enabled port.
Source Files