Describes the steps taken to read and validate a WARC record.
The goal of this WARC library was to make a small package to read and validate WARC files.
The WARC parser was implemented on the premise that WARC data would be supplied in the form of streams and not files.
So the basic operation of parsing and validating a WARC file is a sequential operation where each record and its payload is only read once.
This is also the case when parsing/validating compressed WARC files where each record is GZip'ed. In which case the compressed data can also only be processed sequentially.
It is however possible to random access individual WARC records when working with the logical files and using a file offset.
Steps to parsing a WARC record:
One line is read at a time and compared to a valid WARC version line. The parser is faily strict and will accept "WARC/" and an invalid version string.
Accepted version strings are in the format of "x.x\[x.x\]" even though this will most likely never happen. Wiki Markup
Warnings/Errors range from leading garbage before a valid WARC identifier line to invalid version information and missing CR-LF pairs.
Warnings/Errors reported are restricted to the presence of more or less that two linefeeds.
The WARC reader can be used to read either all the records in a file sequentially or select records in random order.
Both scenarios are supported by the various factory and reader methods.
Besides uncompressed WARC files, GZip compressed files are also supported.
GZip compression is only supported on WARC files where each record is compressed individually and concatenated into one file and not the case where the whole WARC file and all it's records are GZip'ed as a whole. The later mostly because this makes random access to individual record highly ineffective.
The payload is inaccessible when the "Content-Length" is absent or invalid.
Warc-Payload-Digest header is computed only on defined record payloads where the leading header has been read. This makes it a requirement for the WARC parser to identify and always parse the http response and not make it optional.
For GZip'ed records this is not a big problem since we know the record ends when the GZip entry ends.
For uncompressed records the payload input stream would have to look ahead for a valid WARC version line at which point the payload stream should be closed and the bytes read beyond that pushed back onto the internal streams.