nntp

README

nntp

A dependency-free, pure-Go NNTP (Usenet) read client following RFC 3977. It uses only the Go standard library (net, net/textproto, crypto/tls, ...), builds with CGO_ENABLED=0, and pulls in zero third-party dependencies.

Supported operations: connect (plaintext or implicit TLS), AUTHINFO authentication, GROUP selection, OVER overview retrieval, ARTICLE fetching, and LIST ACTIVE newsgroup enumeration.

Install

go get github.com/go-newsgroups/nntp

Requires Go 1.26.4 or newer.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/go-newsgroups/nntp"
)

func main() {
	ctx := context.Background()

	// Dial plaintext (port 119) — use nntp.DialTLS for implicit TLS (port 563).
	c, err := nntp.Dial(ctx, "news.example.org")
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()

	// Optional authentication.
	if err := c.Authenticate("user", "pass"); err != nil {
		log.Fatal(err)
	}

	// Select a group.
	g, err := c.Group("comp.lang.go")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s: %d articles (%d-%d)\n", g.Name, g.Count, g.Low, g.High)

	// Read the overview for the last 10 articles.
	over, err := c.Over(g.High-9, g.High)
	if err != nil {
		log.Fatal(err)
	}
	for _, o := range over {
		fmt.Printf("#%d  %s  (%s)\n", o.ArticleNum, o.Subject, o.From)
	}
}

API

Method	NNTP command	Purpose
Dial / DialTLS	—	Connect (plaintext / implicit TLS) and read the greeting
Authenticate	AUTHINFO USER/PASS	Authenticate
Group	GROUP	Select a newsgroup
Over	OVER	Fetch article header summaries for a range
Article	ARTICLE	Fetch a full article by message-id or number
List	LIST ACTIVE	Enumerate newsgroups (optional wildmat filter)
Close	QUIT	Close the connection

License

BSD-3-Clause. See LICENSE. Copyright the go-newsgroups/nntp authors.

Documentation

Overview

Package nntp implements a dependency-free NNTP (Usenet) read client following RFC 3977. It uses only the Go standard library (CGO_ENABLED=0) and speaks the command/response protocol over net/textproto.

The client is intended for reading: connecting, authenticating, selecting groups, listing overviews, fetching articles and enumerating newsgroups.

Index

• type Article
• type Conn
  • func Dial(ctx context.Context, addr string) (*Conn, error)
  • func DialTLS(ctx context.Context, addr string, tlsConfig *tls.Config) (*Conn, error)
  • func (c *Conn) Article(msgIDorNum string) (*Article, error)
  • func (c *Conn) Authenticate(user, pass string) error
  • func (c *Conn) Close() error
  • func (c *Conn) Group(name string) (*Group, error)
  • func (c *Conn) List(wildmat string) ([]NewsgroupInfo, error)
  • func (c *Conn) Over(low, high int) ([]Overview, error)
• type Group
• type NewsgroupInfo
• type Overview

Types

type Article

type Article struct {
	Headers map[string][]string
	Body    string
}

Article is a complete article: canonicalized headers plus the raw body.

type Conn

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

Conn is a connection to an NNTP server. It wraps a *textproto.Conn layered over the underlying net.Conn. A Conn is not safe for concurrent use.

func Dial

func Dial(ctx context.Context, addr string) (*Conn, error)

Dial connects (plaintext) to addr ("host:port"); if no port is present the default NNTP port 119 is used. The greeting is read and validated.

func DialTLS

func DialTLS(ctx context.Context, addr string, tlsConfig *tls.Config) (*Conn, error)

DialTLS connects with implicit TLS to addr; if no port is present the default NNTPS port 563 is used. tlsConfig may be nil, in which case the platform defaults are used.

func (*Conn) Article

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

Article fetches a full article by message-id ("<...>") or by article number, using the ARTICLE command. Headers are split from the body on the first blank line and canonicalized.

func (*Conn) Authenticate

func (c *Conn) Authenticate(user, pass string) error

Authenticate performs AUTHINFO USER/PASS authentication.

func (*Conn) Close

func (c *Conn) Close() error

Close sends QUIT (best effort) and closes the underlying connection.

func (*Conn) Group

func (c *Conn) Group(name string) (*Group, error)

Group selects the named newsgroup and returns its estimated article count and low/high water marks, parsed from a "211 count low high name" response.

func (*Conn) List

func (c *Conn) List(wildmat string) ([]NewsgroupInfo, error)

List returns the available newsgroups via LIST ACTIVE. If wildmat is non-empty it is passed to the server to filter the result.

func (*Conn) Over

func (c *Conn) Over(low, high int) ([]Overview, error)

Over returns the overview (header summaries) for the inclusive article range low-high in the currently selected group, via the OVER command.

type Group

type Group struct {
	Name  string
	Count int
	Low   int
	High  int
}

Group is the result of selecting a newsgroup with GROUP.

type NewsgroupInfo

type NewsgroupInfo struct {
	Name   string
	High   int
	Low    int
	Status string
}

NewsgroupInfo describes an available newsgroup as listed by LIST ACTIVE.

type Overview

type Overview struct {
	ArticleNum int
	Subject    string
	From       string
	Date       time.Time
	MessageID  string
	References string
	Bytes      int
	Lines      int
}

Overview holds the header summary of a single article, as returned by OVER.