newznab

README

newznab

A pure-Go, dependency-free client for the Newznab Usenet indexer API. It works both against direct Newznab indexers (nzbgeek, NZBFinder, DrunkenSlug, …) and against NZBHydra2, which exposes a Newznab-superset API.

• CGO-free (CGO_ENABLED=0) and zero third-party dependencies — standard library only.
• Newznab t=search and t=caps endpoints.
• Network-free tests, base URL overridable for full testability.

Install

go get github.com/go-newsgroups/newznab

Usage

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	// Works with a direct indexer or an NZBHydra2 instance — pass the root URL.
	c := newznab.New("https://api.nzbgeek.info", "YOUR_API_KEY")

	res, err := c.Search(context.Background(), newznab.SearchOptions{
		Query:      "ubuntu 24.04",
		Categories: []int{4000}, // e.g. PC
		Limit:      50,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%d of %d results\n", len(res.Items), res.Total)
	for _, it := range res.Items {
		fmt.Printf("%s (%d bytes)\n  %s\n", it.Title, it.Size, it.NZBURL)
	}

	// Discover available categories.
	cats, err := c.Capabilities(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	for _, cat := range cats {
		fmt.Printf("%s: %s\n", cat.ID, cat.Name)
	}
}

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package newznab is a dependency-free client for the Newznab indexer API.

It targets the Newznab Usenet search API and also works against NZBHydra2, which exposes a Newznab-superset API. The client is CGO-free and uses only the Go standard library.

Index

• type Category
• type Client
  • func New(baseURL, apiKey string, opts ...Option) *Client
  • func (c *Client) Capabilities(ctx context.Context) ([]Category, error)
  • func (c *Client) Search(ctx context.Context, opts SearchOptions) (*SearchResult, error)
• type Item
• type Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithUserAgent(ua string) Option
• type SearchOptions
• type SearchResult

Types

type Category

type Category struct {
	ID      string
	Name    string
	Subcats []Category
}

Category is a capability category, possibly with subcategories.

type Client

type Client struct {
	// BaseURL is the indexer root, e.g. https://api.nzbgeek.info.
	BaseURL string
	// APIKey is the indexer API key.
	APIKey string
	// HTTPClient is used for all requests. Defaults to http.DefaultClient.
	HTTPClient *http.Client
	// UserAgent is sent on every request.
	UserAgent string
}

Client is a Newznab / NZBHydra2 API client.

func New

func New(baseURL, apiKey string, opts ...Option) *Client

New creates a Client for the given indexer root and API key.

func (*Client) Capabilities

func (c *Client) Capabilities(ctx context.Context) ([]Category, error)

Capabilities performs a t=caps query and returns the category tree.

func (*Client) Search

func (c *Client) Search(ctx context.Context, opts SearchOptions) (*SearchResult, error)

Search performs a t=search query against the indexer.

type Item

type Item struct {
	Title       string
	GUID        string
	NZBURL      string // the .nzb download link (item <link> or <enclosure url>)
	Category    string
	Size        int64     // bytes (from newznab:attr name="size" or <enclosure length>)
	PublishDate time.Time // <pubDate>, RFC1123Z
	Group       string    // newznab:attr name="group" (may be empty)
	Poster      string    // newznab:attr name="poster" (may be empty)
	Grabs       int       // newznab:attr name="grabs" (0 if absent)
}

Item is a single search result.

type Option

type Option func(*Client)

Option configures a Client.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets a custom *http.Client.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets a custom User-Agent header.

type SearchOptions

type SearchOptions struct {
	Query      string
	Categories []int  // newznab category ids
	Group      string // limit to a newsgroup
	Limit      int
	Offset     int
}

SearchOptions parameterises a Search call.

type SearchResult

type SearchResult struct {
	Items  []Item
	Total  int // from <newznab:response total=...> when present, else len(Items)
	Offset int
}

SearchResult is the outcome of a Search call.