///|
/// Representation established by FAR: VAX F/D or IEEE big/little endian.
#derive(Debug, Eq)
pub(all) enum ByteOrder {
Little
Big
Vax
}
///|
/// Errors always identify the absolute byte offset of the failed input.
#derive(Debug)
pub suberror StdfError {
StdfError(Int32, String)
}
///|
/// Raw record body is retained even for unrecognized record types.
#derive(Debug, Eq)
pub(all) struct Frame {
offset : Int32
typ : Int32
sub : Int32
order : ByteOrder
body : Bytes
}
///|
/// Stateful, single-use bounded incremental decoder. Errors poison the decoder.
pub struct Framer {
pending : Array[Byte]
mut target : Int32
mut offset : Int32
mut received : Int32
mut count : Int32
mut order : ByteOrder?
mut closed : Bool
max_bytes : Int32
max_records : Int32
}
///|
pub fn Framer::new(
max_bytes~ : Int32 = 268435456,
max_records~ : Int32 = 1000000,
) -> Framer {
{
pending: [],
target: 6,
offset: 0,
received: 0,
count: 0,
order: None,
closed: false,
max_bytes,
max_records,
}
}
///|
pub fn Framer::feed(
self : Framer,
chunk : Bytes,
) -> Array[Frame] raise StdfError {
if self.closed {
raise StdfError(self.offset, "decoder closed after finish or error")
}
errdefer {
self.closed = true
}
if self.max_bytes < 0 || self.max_records < 0 {
raise StdfError(self.offset, "negative decoder budget")
}
if chunk.length() > self.max_bytes - self.received {
raise StdfError(self.offset, "input byte budget exceeded")
}
self.received += chunk.length()
let out : Array[Frame] = []
// Append each input byte once. The growable current-record buffer avoids
// recopying an ever-growing partial payload for every fragmented feed.
for byte in chunk {
if self.pending.length() == 0 && self.count >= self.max_records {
raise StdfError(self.offset, "record budget exceeded")
}
self.pending.push(byte)
if self.pending.length() != self.target {
continue
}
let data = self.pending
if self.order is None {
if data[2] != 0 || data[3] != 10 || data[5] != 4 {
raise StdfError(0, "expected STDF V4 FAR")
}
let order = match data[4].to_int() {
0 => Vax
1 => Big
2 => Little
_ =>
raise StdfError(
4, "unsupported CPU_TYPE (reserved or customer-defined encoding)",
)
}
let length = if order != Big {
data[0].to_int() | (data[1].to_int() << 8)
} else {
(data[0].to_int() << 8) | data[1].to_int()
}
if length != 2 {
raise StdfError(0, "FAR length must be two")
}
self.order = Some(order)
}
let order = self.order.unwrap()
if data.length() == 4 {
let length = if order != Big {
data[0].to_int() | (data[1].to_int() << 8)
} else {
(data[0].to_int() << 8) | data[1].to_int()
}
self.target = length + 4
if self.target != 4 {
continue
}
}
let typ = data[2].to_int()
let sub = data[3].to_int()
if self.count > 0 && typ == 0 && sub == 10 {
raise StdfError(self.offset, "unexpected second FAR")
}
// Materialize only a complete body; clearing the mutable buffer cannot
// change any already emitted immutable Bytes.
out.push({
offset: self.offset,
typ,
sub,
order,
body: Bytes::from_array(data[4:]),
})
self.offset += self.target
self.count += 1
self.pending.clear()
self.target = 4
}
out
}
///|
/// Call at EOF: a truncated final record is an error, not a successful prefix.
pub fn Framer::finish(self : Framer) -> Unit raise StdfError {
if self.closed {
raise StdfError(self.offset, "decoder closed")
}
self.closed = true
if self.order is None || self.pending.length() != 0 {
raise StdfError(self.offset, "truncated FAR, record header or payload")
}
}
///|
pub fn decode_frames(data : Bytes) -> Array[Frame] raise StdfError {
let framer = Framer::new()
let records = framer.feed(data)
framer.finish()
records
}
///|
pub extend ByteOrder with @debug.Debug::{to_repr}
///|
pub extend ByteOrder with Eq::{equal, not_equal}
///|
pub extend Frame with @debug.Debug::{to_repr}
///|
pub extend Frame with Eq::{equal, not_equal}
///|
pub extend StdfError with @debug.Debug::{to_repr}