Documentation
¶
Overview ¶
Package par2 parses PAR2 2.0 metadata and performs bounded GF16 recovery. File descriptions name obfuscated posts and authenticate source slices. recovery.go reconstructs selected byte intervals, verifies complete target slices, and can subtract retained summaries of already verified input.
The parser is defensive: packets are located by scanning for the magic, every packet's MD5 is verified, corrupt, truncated and unknown packets are skipped and repeated packets (PAR2 files repeat critical packets) are de-duplicated.
Index ¶
- Constants
- Variables
- func Hash16k(prefix []byte, length int64) ([16]byte, bool)
- type Block
- type Field
- type File
- type Hole
- type ID
- type Layout
- type Main
- type MismatchError
- type ReadRange
- type Recovery
- type RecoveryScanner
- type RepairOptions
- type RepairStats
- type Set
- func (s *Set) ByLength(n int64) []*File
- func (s *Set) Identify(prefix []byte, size int64) (f *File, byHash bool)
- func (s *Set) Match16k(sum [16]byte) []*File
- func (s *Set) Named(name string) []*File
- func (s *Set) RecoveryLayout(id ID, maxSlice int64) (*Layout, error)
- func (s *Set) SortedNames() []string
- type Slice
- type Summaries
Constants ¶
const ( TypeMain = "PAR 2.0\x00Main\x00\x00\x00\x00" TypeFileDesc = "PAR 2.0\x00FileDesc" TypeIFSC = "PAR 2.0\x00IFSC\x00\x00\x00\x00" TypeCreator = "PAR 2.0\x00Creator\x00" TypeUniName = "PAR 2.0\x00UniFileN" TypeRecovery = "PAR 2.0\x00RecvSlic" )
Packet types.
const Hash16kSize = 16 * 1024
Hash16kSize is how many leading bytes the "first 16k" MD5 covers.
const HeaderSize = 64
HeaderSize is the size of a packet header.
const Magic = "PAR2\x00PKT"
Magic starts every PAR2 packet.
Variables ¶
var ErrErasure = errors.New("par2: missing or corrupt range")
var ErrInsufficient = errors.New("par2: insufficient independent recovery equations")
var ErrNoFiles = errors.New("par2: no valid file description packets")
ErrNoFiles is returned by Parse when the data holds no valid File Description packet.
Functions ¶
Types ¶
type Field ¶ added in v0.2.8
type Field struct {
// contains filtered or unexported fields
}
Field is PAR2's GF(2^16), constructed explicitly (no mutable global tables).
func (*Field) Coefficient ¶ added in v0.2.8
type File ¶
type File struct {
SetID ID
ID ID
// Name is the file name as stored (the Unicode name when the set has
// one). It may contain a relative path; use path.Base for display.
Name string
Length int64
MD5 [16]byte // MD5 of the whole file
MD5_16k [16]byte // MD5 of the first min(16 KiB, Length) bytes
// SliceSize is the recovery set's slice size, 0 if the Main packet was
// not seen. Slices are the IFSC checksums, nil if absent.
SliceSize int64
Slices []Slice
}
File is one file of a recovery set.
func (*File) Verify ¶
Verify checks a file's leading bytes (prefix) and, when known (> 0), its size against the recorded checksums: the length, the first-16k MD5, every slice prefix fully covers (CRC32 and MD5) and, when prefix is the whole file, its MD5. It returns how many checks ran (0 when prefix is too short to check anything) and a *MismatchError on the first failure.
type Layout ¶ added in v0.2.8
func (*Layout) Recover ¶ added in v0.2.8
func (l *Layout) Recover(ctx context.Context, f *Field, holes []Hole, read ReadRange, parity []Recovery, s *Summaries, opts RepairOptions) (map[int][]byte, RepairStats, error)
Recover reconstructs and verifies complete target slices, but reads only the damaged intervals from other slices. Helpers missing at the same interval become additional unknowns. Nothing is returned until ALL targets verify.
type MismatchError ¶
type MismatchError struct {
Name string
What string // "length", "first 16 KiB MD5", "slice N MD5", "slice N CRC32", "file MD5"
Detail string
}
MismatchError says which PAR2 checksum the content failed.
func (*MismatchError) Error ¶
func (e *MismatchError) Error() string
type ReadRange ¶ added in v0.2.8
ReadRange reads exactly len(dst) bytes within one padded input slice. Missing or corrupt data must wrap ErrErasure; transport failures must not.
type RecoveryScanner ¶ added in v0.2.8
RecoveryScanner accepts consecutive decoded article bytes and releases valid recovery packets incrementally. Reset at every unavailable/nonconsecutive article; complete packets on either side of a hole remain usable.
func (*RecoveryScanner) Push ¶ added in v0.2.8
func (s *RecoveryScanner) Push(data []byte, limit int) []Recovery
func (*RecoveryScanner) Reset ¶ added in v0.2.8
func (s *RecoveryScanner) Reset()
type RepairOptions ¶ added in v0.2.8
type RepairStats ¶ added in v0.2.8
type Set ¶
type Set struct {
// Main retains the protected-file order required by the recovery equations.
Main map[ID]Main
// Files in order of first appearance.
Files []*File
// Creator is the first Creator packet's text, for diagnostics.
Creator string
// Packets counts valid, distinct packets; Skipped counts packet
// headers that were corrupt, truncated or of an unusable type.
Packets int
Skipped int
}
Set is everything usable found in one or more PAR2 files. Files from several recovery sets may be present.
func Parse ¶
Parse scans data (one or more concatenated PAR2 files, possibly with junk or gaps from missing articles) for packets. It returns ErrNoFiles if no valid File Description packet is found.
func (*Set) Identify ¶
Identify finds the file whose content starts with prefix and, if size > 0, is size bytes long. The first-16k MD5 decides when prefix covers it (and must then be unique among the files of that length); otherwise, or when no hash matches, a unique exact length does. byHash reports which rule matched. A file found by length alone whose 16k hash did not match is still returned, so the caller can name it and report the mismatch.
func (*Set) Named ¶
Named returns the files whose base name is name: exact matches, or, if there are none, case-insensitive ones.
func (*Set) RecoveryLayout ¶ added in v0.2.8
RecoveryLayout rejects incomplete metadata rather than guessing coefficient order, treating unprotected files as protected, or allocating from huge sizes.
func (*Set) SortedNames ¶
SortedNames lists the base names of the set's files, sorted (for logs).
type Slice ¶
Slice is the checksum pair of one input slice. The last slice of a file is hashed zero-padded to the slice size.
type Summaries ¶ added in v0.2.8
type Summaries struct {
Exponents []uint32
Data [][]byte
Seen []bool
// contains filtered or unexported fields
}
Summaries retain verified contributions to fixed recovery equations. Caller serializes access. A coverage bit is committed only after the contribution. Duplicate observations are harmless. No raw source data is retained here.
Source Files
Directories