// Frames read without decoding them (RFC 8878 sections 3.1.1 and 3.1.2):
// what a frame header says, where a frame ends, and skippable frames, which
// carry the caller's bytes and which decoders pass over.
///|
/// The first magic number of skippable frames: the 16 numbers from it to
/// 0x184D2A5F all start one, their low four bits the frame's variant.
const SKIPPABLE_MAGIC : UInt32 = 0x184D2A50
///|
/// What a Zstandard frame's header says, as `inspect_frame` reads it.
#derive(Eq, @debug.Debug)
pub struct FrameInfo {
/// Window_Size in bytes: the history a decoder keeps for the frame, from
/// the window descriptor, or the content size of a single-segment frame.
window_size : UInt64
/// Frame_Content_Size, when the header has the field.
content_size : UInt64?
/// Dictionary_ID: the dictionary the frame needs, or 0 for none.
dictionary_id : UInt32
/// Content_Checksum_Flag: the frame ends with four bytes of XXH64.
has_checksum : Bool
/// Single_Segment_Flag: the window is the content size.
single_segment : Bool
/// The bytes before the first block: the magic number and the header, 6
/// to 18.
header_len : Int32
}
///|
/// Compares two frame headers read by `inspect_frame`, field by field.
pub extend FrameInfo with Eq::{equal, not_equal}
///|
/// Shows the frame header as its fields, for tests and messages.
pub extend FrameInfo with @debug.Debug::{to_repr}
///|
/// The frame at the start of some bytes, as `inspect_frame` sees it.
#non_exhaustive
#derive(Eq, @debug.Debug)
pub(all) enum Frame {
/// A Zstandard frame, and what its header says.
Zstd(FrameInfo)
/// A skippable frame: its variant, 0 to 15 (the magic number's low four
/// bits), and how many bytes of the caller's it holds after its 8-byte
/// header.
Skippable(variant~ : Int32, size~ : UInt32)
}
///|
/// Compares two frames read by `inspect_frame`, field by field.
pub extend Frame with Eq::{equal, not_equal}
///|
/// Shows the frame as its fields, for tests and messages.
pub extend Frame with @debug.Debug::{to_repr}
///|
/// `n` bytes from `at`, little-endian; the caller has checked they are there.
fn read_le(input : BytesView, at : Int32, n : Int32) -> UInt64 {
let mut value = 0UL
for i = n - 1; i >= 0; i = i - 1 {
value = (value << 8) | input[at + i].to_uint64()
}
value
}
///|
fn truncated(what : String) -> @codec.CodecError {
CodecError(Truncated, "the input ends inside \{what}")
}
///|
/// Reads the header of the frame at the start of `input` without decoding
/// it: a Zstandard frame's window, content size, dictionary and checksum
/// flag, or a skippable frame's variant and size. Only the header's bytes
/// are read.
///
/// Raises `Truncated` if `input` ends inside the header, and `Corrupt` if it
/// starts with neither magic number or the header's reserved bit is set. A
/// window or a dictionary is not judged here: `Decoder` judges those.
pub fn inspect_frame(input : BytesView) -> Frame raise @codec.CodecError {
guard input.length() >= 4 else { raise truncated("a magic number") }
let magic = read_le(input, 0, 4).to_uint()
if (magic & 0xFFFFFFF0) == SKIPPABLE_MAGIC {
guard input.length() >= 8 else {
raise truncated("a skippable frame's header")
}
return Skippable(
variant=(magic & 0xF).reinterpret_as_int(),
size=read_le(input, 4, 4).to_uint(),
)
}
guard magic == FRAME_MAGIC else {
raise CodecError(Corrupt, "not a zstd frame")
}
guard input.length() >= 5 else { raise truncated("a frame header") }
let len = match @header.frame_header_len(input[4].to_int()) {
Ok(len) => len
Err(message) => raise CodecError(Corrupt, message)
}
guard input.length() >= 4 + len else { raise truncated("a frame header") }
let bytes = FixedArray::makei(len, i => input[4 + i])
let header = match @header.parse_frame_header(bytes[:]) {
Ok(header) => header
Err(message) => raise CodecError(Corrupt, message)
}
Zstd({
window_size: header.window_size,
content_size: header.content_size,
dictionary_id: header.dictionary_id,
has_checksum: header.has_checksum,
single_segment: header.single_segment,
header_len: 4 + header.header_len,
})
}
///|
/// The length of the frame at the start of `input`, a Zstandard frame or a
/// skippable one, found by reading its header and walking its block headers
/// (an RLE block holds one byte, a raw or compressed block its size) and its
/// checksum, without decoding anything; `input[frame_size(input):]` is what
/// follows the frame. As zstd's `ZSTD_findFrameCompressedSize`.
///
/// Raises `Truncated` if `input` ends inside the frame, and `Corrupt` for
/// what `inspect_frame` refuses and for a block of the reserved type. The
/// blocks' contents are not checked: `Decoder` does that.
pub fn frame_size(input : BytesView) -> Int64 raise @codec.CodecError {
match inspect_frame(input) {
Skippable(size~, ..) => {
let total = 8L + size.to_int64()
guard input.length().to_int64() >= total else {
raise truncated("a skippable frame")
}
total
}
Zstd(info) => {
let mut at = info.header_len
for ;; {
guard input.length() - at >= 3 else {
raise truncated("a block header")
}
let block = match
@header.parse_block_header(read_le(input, at, 3).to_int()) {
Ok(block) => block
Err(message) => raise CodecError(Corrupt, message)
}
let body = if block.block_type is Rle { 1 } else { block.size }
guard input.length() - at - 3 >= body else {
raise truncated("a block")
}
at += 3 + body
if block.last {
break
}
}
if info.has_checksum {
guard input.length() - at >= 4 else {
raise truncated("the content checksum")
}
at += 4
}
at.to_int64()
}
}
}
///|
/// A skippable frame of `variant` (its low four bits are used) holding
/// `data`: the magic number `0x184D2A50 + variant`, the length of `data` in
/// four little-endian bytes, then `data`. Decoders skip it, so it carries
/// bytes of the caller's beside Zstandard frames, as the header of RFC
/// 9842's `dcz` coding does.
pub fn skippable_frame(variant : Int32, data : BytesView) -> Bytes {
let magic = SKIPPABLE_MAGIC | (variant & 0xF).reinterpret_as_uint()
let n = data.length().reinterpret_as_uint()
let out = Buffer(size_hint=8 + data.length())
out.write_uint_le(magic)
out.write_uint_le(n)
out.write_bytesview(data)
out.to_bytes()
}
///|
/// The variant and the data of the skippable frame at the start of `input`,
/// a view into `input`. Raises `Truncated` if `input` ends inside the frame,
/// and `Corrupt` if it does not start with a skippable frame.
pub fn read_skippable_frame(
input : BytesView,
) -> (Int32, BytesView) raise @codec.CodecError {
match inspect_frame(input) {
Skippable(variant~, size~) => {
guard input.length().to_int64() - 8L >= size.to_int64() else {
raise truncated("a skippable frame")
}
(variant, input[8:8 + size.reinterpret_as_int()])
}
_ => raise CodecError(Corrupt, "not a skippable frame")
}
}