newznab

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: GPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package newznab is a Newznab and Torznab indexer for a live suite to run beside the server under test: one listener, any number of indexers at /<name>/api, each usenet or torrent, each healthy or broken as the test says. The test decides which releases exist and sees every request.

The test's data is the test's to decide: a release must say its title and category. What it need not say but a feed must carry, the date and a torrent's size, is picked from a spread by a seed (Options.Seed), so no test leans on a fixed made-up value; Indexer.Releases says what was picked. Every answer is in the shape the *arr parsers read, and a comment that names one says why the answer is as it is. Links in the feeds use the address the container reaches the host by (Options.PublicHost).

Index

Constants

View Source
const (
	Usenet  = "usenet"
	Torrent = "torrent"
)

The protocols an indexer speaks: Newznab for usenet, Torznab for torrents.

View Source
const (
	SearchText  = "search"
	SearchTV    = "tv-search"
	SearchMovie = "movie-search"
	SearchMusic = "music-search"
	SearchBook  = "book-search"
)

The kinds of search an indexer's capabilities list, for Site.Searches.

View Source
const (
	CategoryMovies        = 2000
	CategoryMoviesSD      = 2030
	CategoryMoviesHD      = 2040
	CategoryMoviesUHD     = 2045
	CategoryAudio         = 3000
	CategoryTV            = 5000
	CategoryTVForeign     = 5020
	CategoryTVSD          = 5030
	CategoryTVHD          = 5040
	CategoryTVUHD         = 5045
	CategoryTVOther       = 5050
	CategoryTVSport       = 5060
	CategoryTVAnime       = 5070
	CategoryTVDocumentary = 5080
	CategoryBooks         = 7000
)

The standard categories. A release is filed under one subcategory, and a search for its parent (2000, 5000) finds it too.

View Source
const (
	ErrIncorrectCredentials = 100
	ErrMissingParameter     = 200
	ErrIncorrectParameter   = 201
	ErrNoSuchFunction       = 202
	ErrNoSuchItem           = 300
	ErrRequestLimitReached  = 500
	ErrUnknown              = 900
)

The Newznab error codes an indexer answers with. The *arrs read 100-199 as a key that was refused, and 500 as a request limit to back off from.

View Source
const DefaultPageSize = 100

DefaultPageSize is the page size an indexer advertises and serves unless its Site says otherwise.

Variables

View Source
var DefaultCategories = []Category{
	{ID: CategoryMovies, Name: "Movies", Subs: []Category{{ID: CategoryMoviesSD, Name: "SD"}, {ID: CategoryMoviesHD, Name: "HD"}, {ID: CategoryMoviesUHD, Name: "UHD"}}},
	{ID: CategoryTV, Name: "TV", Subs: []Category{{ID: CategoryTVForeign, Name: "Foreign"}, {ID: CategoryTVSD, Name: "SD"}, {ID: CategoryTVHD, Name: "HD"}, {ID: CategoryTVUHD, Name: "UHD"}, {ID: CategoryTVOther, Name: "Other"}, {ID: CategoryTVSport, Name: "Sport"}, {ID: CategoryTVAnime, Name: "Anime"}, {ID: CategoryTVDocumentary, Name: "Documentary"}}},
}

DefaultCategories are movies and TV with their subcategories, which is what Sonarr's and Radarr's own default categories are found in.

Functions

This section is empty.

Types

type Category

type Category struct {
	ID   int
	Name string
	Subs []Category
}

Category is a category an indexer's capabilities list, with its subcategories.

type Failure

type Failure struct {
	// Status, when set, is the HTTP status every call answers, the way an indexer that is down answers a 503.
	Status int
	// Code, when set and Status is not, answers every call with a Newznab error document under HTTP 200: a key the indexer has revoked
	// (ErrIncorrectCredentials) or a request limit (ErrRequestLimitReached).
	Code        int
	Description string
	// Every, when above 1, fails every Every-th search and answers the rest; capabilities and downloads always answer. A failure lasts failureSpell,
	// longer than an *arr's retries, which would otherwise hide it.
	Every int
}

Failure is how an indexer misbehaves; the zero value is healthy.

type Indexer

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

Indexer is one indexer a Server serves.

func (*Indexer) Grabbed

func (ix *Indexer) Grabbed() []string

Grabbed is the titles fetched from the indexer, in order.

func (*Indexer) LocalURL

func (ix *Indexer) LocalURL() string

LocalURL is the indexer's address from this process.

func (*Indexer) Name

func (ix *Indexer) Name() string

Name is the name the indexer is served under.

func (*Indexer) Offer

func (ix *Indexer) Offer(releases ...Release) error

Offer adds releases to the catalogue, each in place of any with its GUID, or adds none when one is refused (Release).

func (*Indexer) Releases

func (ix *Indexer) Releases() []Release

Releases is the catalogue, unsaid values decided and grabs counted.

func (*Indexer) Requests

func (ix *Indexer) Requests() []Request

Requests are the calls the indexer received, oldest first.

func (*Indexer) SetDelay

func (ix *Indexer) SetDelay(d time.Duration)

SetDelay changes how long the indexer holds its answers back.

func (*Indexer) SetFailure

func (ix *Indexer) SetFailure(f Failure)

SetFailure changes how the indexer misbehaves; the zero Failure mends it.

func (*Indexer) SetReleases

func (ix *Indexer) SetReleases(releases ...Release) error

SetReleases replaces the catalogue, or leaves it as it was when a release is refused (Release).

func (*Indexer) URL

func (ix *Indexer) URL() string

URL is the indexer's address as the container reaches it, the base URL an *arr is given with /api as its path.

func (*Indexer) Withdraw

func (ix *Indexer) Withdraw(titles ...string)

Withdraw takes releases out of the catalogue by title.

type Options

type Options struct {
	// Addr is where to listen, ":18081"; empty picks a free port on 127.0.0.1. A live run listens on every interface for the container.
	Addr string
	// PublicHost is the name the container reaches this machine by, which the feeds' links use; empty is 127.0.0.1.
	PublicHost string
	// Sites are the indexers to serve from the start.
	Sites []Site
	// Seed decides the date and torrent size a release is given when it says neither, each from a spread. The same seed gives the same again; 0 picks
	// one and prints it on stderr, where a failing run's output is.
	Seed uint64
}

Options configure a Server.

type Release

type Release struct {
	// GUID identifies the release in its links; empty derives a stable one from the title.
	GUID string
	// Title is the scene name an *arr parses the series or film, the quality and the group from.
	Title string
	// Size is the release's size in bytes; 0 is unknown. A torrent must hold something, Prowlarr refuses one of nothing, so a torrent that does not
	// say is given a size (Options.Seed).
	Size int64
	// PubDate is when it was posted. Sonarr refuses a whole feed for one item without a date, so one that does not say is given a date
	// (Options.Seed), kept however often it is offered.
	PubDate time.Time
	// Category is the subcategory it is filed under, which decides the searches that find it; a release without one is refused.
	Category int
	// IMDBID, TMDBID, TVDBID and TvMazeID are what a search by id matches. IMDBID is written with or without its tt.
	IMDBID   string
	TMDBID   int
	TVDBID   int
	TvMazeID int
	// Season and Episode are what a TV search by season and episode matches. Episode 0 is a season pack.
	Season  int
	Episode int
	// Seeders and Peers are what a torrent indexer reports, and Freeleech a torrent that costs no download ratio.
	Seeders   int
	Peers     int
	Freeleech bool
	// Grabs counts the times it was fetched.
	Grabs int
	// Files is the number of files its NZB lists; 0 is one.
	Files int
	// Group and Poster are the usenet group and poster the feed and the NZB name; empty is a made-up one of each.
	Group  string
	Poster string
	// Languages are language names (English, German) an *arr reads from the feed rather than the title.
	Languages []string
	// Scene and Nuked set the prematch and nuked attributes an *arr turns into indexer flags.
	Scene bool
	Nuked bool
}

Release is one entry in an indexer's catalogue.

type Request

type Request struct {
	// Site is the name of the indexer asked.
	Site   string
	Method string
	Path   string
	// Function is the t= parameter (caps, search, tvsearch, movie), or "download" for a fetch of a release.
	Function string
	// Query is every parameter as sent, the API key included.
	Query url.Values
	Time  time.Time
}

Request is one call an indexer received.

type Server

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

Server is the listener the indexers are served from.

func New

func New(opts Options) (*Server, error)

New starts a server listening on opts.Addr.

func (*Server) Add

func (s *Server) Add(site Site) (*Indexer, error)

Add starts serving an indexer, in place of any of the same name.

func (*Server) Addr

func (s *Server) Addr() string

Addr is the address listened on.

func (*Server) Close

func (s *Server) Close() error

Close stops the server at once; a graceful stop would wait on idle connections.

func (*Server) Indexer

func (s *Server) Indexer(name string) *Indexer

Indexer is the indexer served under a name, nil when there is none.

func (*Server) Port

func (s *Server) Port() int

Port is the port listened on.

func (*Server) Requests

func (s *Server) Requests() []Request

Requests are the calls every indexer received, oldest first.

func (*Server) Seed

func (s *Server) Seed() uint64

Seed is the seed this run picked unsaid values by (Options.Seed).

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP answers each indexer under its name: the API at /<name>/api, or any path under the name ending in /api, and a release at /<name>/download/<guid>. An error names the parameter at fault, never what it was sent as.

type Site

type Site struct {
	// Name is its path: its API is at /<Name>/api.
	Name string
	// Protocol is Usenet or Torrent; empty is Usenet.
	Protocol string
	// APIKey is the key every call but capabilities must carry as apikey=; empty accepts any.
	APIKey string
	// Categories are what its capabilities list; nil is DefaultCategories.
	Categories []Category
	// Searches are the kinds of search it offers; nil is SearchText, SearchTV and SearchMovie.
	Searches []string
	// TVSearchParams are the tv-search parameters its capabilities list; nil is q, season, ep and tvdbid. An *arr sends only the ids listed.
	TVSearchParams []string
	// PageSize is the default and largest page it serves; 0 is DefaultPageSize.
	PageSize int
	// Releases is its catalogue to start with.
	Releases []Release
	// Delay holds every answer back this long, the way a slow indexer does.
	Delay time.Duration
	// Failure is how it misbehaves.
	Failure Failure
}

Site describes one indexer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL