nzb

package
v0.3.18 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package nzb parses NZB documents: the XML index of a Usenet post that lists every file, its newsgroups and the message IDs of its segments (articles). Besides the raw structure it derives file names from subjects, classifies files (video, archive volumes, par2, extras), flags obfuscated names and groups archive volumes into ordered sets, which is what the stream engine needs to find the playable file of a release.

Index

Constants

View Source
const ContentIDPrefix = "nzb:"

ContentIDPrefix namespaces NZB content identities derived from segment message-IDs.

View Source
const MetaEpisode = "ether-episode"

MetaEpisode is the <meta> type that tells the stream engine which episode of a multi-episode archive to play ("season:episode:absolute[,s:e...]").

View Source
const MetaMovie = "ether-movie"

MetaMovie carries the requested movie identity and audio language preferences into multi-file NZB and archive member selection.

View Source
const MetaNonVideo = "ether-nonvideo"

MetaNonVideo carries non-video release selection intent (explicit posted file, archive member, or media MIME) from a plugin release target into the stream engine.

View Source
const MetaSubjectNames = "ether-subject-names"

MetaSubjectNames preserves original subject-derived file names (keyed by 0-based file index in the emitted NZB) when re-encoding rewrites a file's subject to carry a PAR2/yEnc-learned name.

Variables

View Source
var ErrInvalid = errors.New("nzb: invalid document")

ErrInvalid is returned for documents that are not usable NZBs.

Functions

func CleanArchivePath

func CleanArchivePath(raw string) string

CleanArchivePath normalises a release or archive member path for matching.

func ContentID

func ContentID(data []byte) string

ContentID returns "nzb:<sha256>" over the sorted unique segment message-IDs in data, or "" when data is not an NZB document with at least one segment.

func ContentSumBytes

func ContentSumBytes(data []byte) ([32]byte, bool)

ContentSumBytes parses data as an NZB and returns its 32-byte content digest.

func FormatContentID

func FormatContentID(sum [32]byte) string

FormatContentID formats a 32-byte NZB content digest as "nzb:<64-char lowercase hex>".

func InspectContent

func InspectContent(data []byte) (contentID, poster string, uploadDate time.Time, totalBytes int64)

InspectContent extracts the NZB content identity ("nzb:<sha256>" over sorted segment message-IDs) together with the first posted file's poster, UTC upload timestamp, and total listed segment bytes. Non-NZB payloads (such as empty slices or JSON descriptors) return zero values.

func IsArchiveMIME

func IsArchiveMIME(raw string) bool

IsArchiveMIME reports whether raw names a generic wrapper archive format (ZIP, RAR, 7z) rather than a self-contained media format like EPUB or CBZ.

func IsNonVideoMIME

func IsNonVideoMIME(raw string) bool

IsNonVideoMIME reports whether raw names a concrete non-video playable media type (audio, ebook, comic, image, or text) suitable for automatic non-video release file selection.

func IsObfuscated

func IsObfuscated(name string) bool

IsObfuscated reports whether a name carries no information about the content: no extension, a hash/UUID-like base, a long random token, or the "abc.xyz" / "b00bs." / "Backup_NNNNNS01-02" placeholders some posters use.

func IsPar2Volume

func IsPar2Volume(name string) bool

IsPar2Volume reports whether name is a PAR2 recovery volume ("x.vol03+04.par2") rather than an index file ("x.par2").

func IsVideoExt

func IsVideoExt(ext string) bool

IsVideoExt reports whether ext (without dot, any case) is a video container.

func MIMEFamily

func MIMEFamily(raw string) string

MIMEFamily maps a MIME type onto a broad non-video or video media family ("audio", "book", "comic", "image", "text", "video", "archive", or "").

func MatchPathIndex

func MatchPathIndex(names []string, want string) (idx int, found bool, ambiguous bool)

MatchPathIndex finds the unique index in names matching want by:

  1. exact normalised path (case-insensitive)
  2. unique suffix path match (when want contains a slash, e.g. "CD1/01.flac" inside "Album/CD1/01.flac")
  3. unique basename match (when want has no slash)

It returns (idx, true, false) on a unique match, (-1, false, true) when multiple entries match ambiguously, or (-1, false, false) when none match.

func MatchTrackIndex

func MatchTrackIndex(names []string, want TrackHint, mimeFilter string) (idx int, found bool, ambiguous bool)

MatchTrackIndex finds a unique audio file in names matching want:

  1. Disc + track number first (disambiguated by normalised title tokens when multiple candidates share a number, failing with ambiguous=true if still not unique).
  2. Normalised title tokens when no track number was given or no candidate matched by number (contiguous token sequence first, then all tokens present), failing with ambiguous=true when multiple candidates tie.

func NameFromSubject

func NameFromSubject(subject string) string

NameFromSubject extracts the file name from a Usenet subject line, e.g.

`"Movie.2024.part01.rar" yEnc (1/50)`                -> Movie.2024.part01.rar
`[01/42] - "Movie.2024.mkv" yEnc (1/1000)`          -> Movie.2024.mkv
`[PRiVATE]-[WtFnZb]-[Movie.2024.mkv]-[1/5] - "" yEnc` -> Movie.2024.mkv
`Concert Recording 2019 Full Show.mkv (1/120)`      -> Concert Recording 2019 Full Show.mkv
`Movie.2024.r00 (1/50)`                             -> Movie.2024.r00

func NonVideoMatchRank

func NonVideoMatchRank(filename, declaredMIME string) int

NonVideoMatchRank scores how well filename matches declaredMIME for automatic non-video release selection:

2 = extension matches the exact declared MIME type
1 = extension belongs to the same non-video media family
0 = not a usable match (wrong family, video, metadata/junk, or no MIME)

func NormalizeMIME

func NormalizeMIME(raw string) string

NormalizeMIME strips parameters and normalises ASCII case on a MIME string.

func ParseContentID

func ParseContentID(id string) ([32]byte, bool)

ParseContentID decodes an "nzb:<64-char hex>" (or bare 64-char hex) content identity into its 32-byte SHA-256 digest.

Types

type EpisodeHint

type EpisodeHint struct {
	Season, Episode, Absolute int
	Aliases                   [][2]int
}

EpisodeHint is the wanted episode of a season held inside an archive.

func (EpisodeHint) String

func (h EpisodeHint) String() string

String is the <meta> value for h.

type File

type File struct {
	Index   int // position in NZB.Files
	Poster  string
	Date    time.Time
	Subject string
	Groups  []string
	// Segments sorted by Number, de-duplicated: the first occurrence of a
	// number wins, later message-IDs for it become its Alternates.
	Segments []Segment

	// Name is the active file name: initially derived from Subject, and
	// potentially updated later from PAR2 or yEnc probing.
	Name string
	// SubjectName is the original name derived from Subject before any
	// PAR2/yEnc rename or re-encoding, preserved across Subset/SubsetMeta.
	SubjectName string
	// Obfuscated reports that Name looks random (hashes, missing extension),
	// so it says nothing about the content.
	Obfuscated bool
	// Info classifies Name.
	Info FileInfo
	// SubjectIndex / SubjectCount are the "[03/50]" file counter in the
	// subject, 0 when absent. Useful to order obfuscated volumes.
	SubjectIndex int
	SubjectCount int
	// ExpectedSegments is the "(1/N)" segment count in the subject, or 0.
	ExpectedSegments int
	// Duplicates counts repeated segment numbers folded into an earlier
	// segment (as Alternates when the message-ID differs).
	Duplicates int
}

File is one posted file.

func Par2Index

func Par2Index(files []*File) *File

Par2Index returns the PAR2 index file among files: the smallest file classified as PAR2 that is not a recovery volume (preferring one that is not a sample's), or nil. The index holds only metadata packets (file names, sizes, hashes), typically a few KB.

func (*File) Bytes

func (f *File) Bytes() int64

Bytes is the sum of the listed segment sizes. It is the encoded article size, a few percent larger than the decoded file; use it for comparisons.

func (*File) EstimatedDecodedBytes

func (f *File) EstimatedDecodedBytes() int64

EstimatedDecodedBytes estimates the decoded payload length from the listed yEnc-encoded segment byte sizes, removing the ~3.1% yEnc escaping and CRLF expansion (1.5625% byte-escaping + 1.5625% line breaks). Callers that rely on this estimate must treat it as approximate rather than exact.

func (*File) Missing

func (f *File) Missing() []int

Missing returns the segment numbers in 1..SegmentCount() that the NZB does not list.

func (*File) OriginalName

func (f *File) OriginalName() string

OriginalName returns the original subject-derived file name before any PAR2/yEnc rename or re-encoding.

func (*File) SegmentCount

func (f *File) SegmentCount() int

SegmentCount is the number of part slots the file has: the highest segment number seen or announced by the subject.

func (*File) StableName

func (f *File) StableName() string

StableName returns a stable selection/listing name for f that does not flip between a readable subject-derived name and a probed PAR2/yEnc name: non-obfuscated files keep their original subject-derived name, while obfuscated files prefer a learned name when known.

type FileInfo

type FileInfo struct {
	Kind Kind
	// Ext is the lower-cased extension of the content: "mkv" for
	// "movie.mkv" and for "movie.mkv.001"; "rar" / "7z" for archives.
	Ext string
	// Volume is the 0-based position of an archive volume in its set
	// (.rar=0, .r00=1, .part01.rar=0, .7z.001=0, .001=0). -1 otherwise.
	Volume int
	// SetName is the lower-cased name shared by every volume of a set, so
	// volumes group by (Kind, SetName). For other files it is the
	// lower-cased name without extension.
	SetName string
	// NewStyle is true for .partNN.rar naming, false for .rar/.rNN.
	NewStyle bool
	// Sample and Extra flag short clips that are not the feature.
	Sample bool
	Extra  bool
}

FileInfo is what a file name says about a posted file.

func Classify

func Classify(name string) FileInfo

Classify interprets a file name (a base name or a path inside an archive).

type Kind

type Kind int

Kind classifies a posted file by its name.

const (
	KindUnknown  Kind = iota
	KindVideo         // a playable container (.mkv, .mp4, ...)
	KindRAR           // a RAR volume (.rar, .r00, .partNN.rar)
	KindSevenZip      // a 7z volume (.7z, .7z.001)
	KindZIP           // a ZIP volume (.zip, .zip.001, .z01)
	KindSplit         // a plain split volume (.001, .mkv.001)
	KindPar2
	KindNFO
	KindSFV
	KindSubtitle
	KindImage
	KindOther // known but irrelevant (.txt, .nzb, .srr, ...)
	KindISO   // a disc image (.iso), played by its main feature
)

func (Kind) IsArchive

func (k Kind) IsArchive() bool

IsArchive reports whether the kind is a volume of a multi-file set.

func (Kind) String

func (k Kind) String() string

type MovieHint

type MovieHint struct {
	Titles           []string `json:"Titles,omitempty"`
	Year             int      `json:"Year,omitempty"`
	WantedLanguages  []string `json:"WantedLanguages,omitempty"`
	OriginalLanguage string   `json:"OriginalLanguage,omitempty"`
}

func (MovieHint) String

func (h MovieHint) String() string

type NZB

type NZB struct {
	// Meta holds <head><meta type="..."> values by lower-cased type.
	Meta map[string][]string
	// Files in document order. Files without any valid segment are dropped.
	Files []*File
}

NZB is a parsed document.

func Parse

func Parse(data []byte) (*NZB, error)

Parse parses an NZB document.

func ParseReader

func ParseReader(r io.Reader) (*NZB, error)

ParseReader parses an NZB document from r.

func (*NZB) ArchiveSets

func (n *NZB) ArchiveSets() []*Set

ArchiveSets groups archive volumes by set and orders them. Sets are returned largest first.

func (*NZB) ContentID

func (n *NZB) ContentID() string

ContentID returns "nzb:<sha256>" for the parsed NZB document, or "" if empty.

func (*NZB) ContentSum

func (n *NZB) ContentSum() ([32]byte, bool)

ContentSum computes the SHA-256 digest over all sorted unique primary segment message-IDs across every file in doc (each normalized without angle brackets and terminated by '\n'). All files are included so subject de-obfuscation differences across indexers never alter the key.

func (*NZB) EpisodeHint

func (n *NZB) EpisodeHint() (EpisodeHint, bool)

EpisodeHint returns the document's episode hint, if it has a valid one.

func (*NZB) MetaValue

func (n *NZB) MetaValue(typ string) string

MetaValue returns the first meta value of a type ("title", "name", ...).

func (*NZB) MovieHint

func (n *NZB) MovieHint() (MovieHint, bool)

func (*NZB) NonVideoHint

func (n *NZB) NonVideoHint() (NonVideoHint, bool)

NonVideoHint returns the document's non-video selection hint, if present.

func (*NZB) Password

func (n *NZB) Password() string

Password returns the first <meta type="password"> value, if any.

func (*NZB) Subset

func (n *NZB) Subset(keep func(*File) bool) (data []byte, ok bool)

Subset returns the NZB restricted to the files keep accepts, keeping the document metadata (such as the password). Parsing the result gives the same file names, segments and repost alternates as the originals. ok is false when no file is kept.

func (*NZB) SubsetMeta

func (n *NZB) SubsetMeta(keep func(*File) bool, extra map[string]string) (data []byte, ok bool)

SubsetMeta is Subset with extra <meta> values added (type -> value). The extra values make the subset a different document, with its own digest.

func (*NZB) TotalBytes

func (n *NZB) TotalBytes() int64

TotalBytes sums every file's listed size.

type NonVideoHint

type NonVideoHint struct {
	ExplicitFile bool       `json:"explicitFile,omitempty"`
	ExactFile    string     `json:"exactFile,omitempty"`
	RawFile      bool       `json:"rawFile,omitempty"`
	Member       string     `json:"member,omitempty"`
	MemberIndex  *int       `json:"memberIndex,omitempty"`
	Track        *TrackHint `json:"track,omitempty"`
	MIME         string     `json:"mime,omitempty"`
}

NonVideoHint tells the stream engine to serve a non-video file directly (loose file or archive member) instead of running video-only heuristics.

func (NonVideoHint) String

func (h NonVideoHint) String() string

type Segment

type Segment struct {
	Number    int    // 1-based part number
	Bytes     int64  // article size as listed in the NZB (encoded, approximate)
	MessageID string // without angle brackets
	// Alternates are message-IDs of reposts ("fills") of this same part,
	// in NZB order, to try when MessageID is missing everywhere. A repost
	// carries the same yEnc part, so its bytes must land on the same range.
	Alternates []string
}

Segment is one article of a file.

type Set

type Set struct {
	Kind Kind
	// Name is the lower-cased set name shared by the volumes
	// ("movie.2024" for movie.2024.part01.rar, "movie.mkv" for movie.mkv.001).
	Name string
	// NewStyle is true for .partNN.rar and .z01+.zip sets.
	NewStyle bool
	// Volumes in order; gaps are listed in Missing. The files' Info is left
	// untouched (a part00/.000 set keeps numbering from -1), so grouping the
	// same files again gives the same result and concurrent callers do not
	// write shared files.
	Volumes []*File
	// Missing lists absent 0-based volume numbers below the highest present.
	Missing []int
	// Duplicates are reposted volumes that lost to a larger copy.
	Duplicates []*File
}

Set is the ordered volumes of one archive (RAR, 7z, ZIP or plain split).

func GroupSets

func GroupSets(files []*File) []*Set

GroupSets groups the archive volumes among files (classified by their Info) into ordered sets, largest first.

func (*Set) Bytes

func (s *Set) Bytes() int64

Bytes sums the listed sizes of the set's volumes.

func (*Set) Complete

func (s *Set) Complete() bool

Complete reports whether no volume is missing (as far as names tell).

type TrackHint

type TrackHint struct {
	Disc   int    `json:"disc,omitempty"`
	Number int    `json:"number,omitempty"`
	Title  string `json:"title,omitempty"`
}

TrackHint identifies a track inside a multi-track audio release or archive.

func (*TrackHint) NonEmpty

func (t *TrackHint) NonEmpty() bool

NonEmpty reports whether the hint specifies a track number or title.

Jump to

Keyboard shortcuts

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